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Section 1 

r* CP/M Features and Facilities 


1.1 Introduction 


fsm CP/M® is a monitor control program for microcomputer system development that 
uses floppy disks or Winchester hard disks for backup storage. Using a computer 
system based on the Intel® 8080 microcomputer, CP/M provides an environment for 
— 1 program construction, storage, and editing, along with assembly and program check- 

■ out facilities. CP/M can be easily altered to execute with any computer configuration 

that uses a Zilog Z80® or an Intel 8080 Central Processing Unit (CPU) and has at least 
20K bytes of main memory with up to 16 disk drives. A detailed discussion of the 
; modifications required for any particular hardware environment is given in Section 6. 

Although the standard Digital Research version operates on a single-density Intel MDS 
800, several different hardware manufacturers support their own input-output (I/O) 
drivers for CP/M. 

i 




The CP/M monitor provides rapid access to programs through a comprehensive file 
management package. The file subsystem supports a named file structure, allowing 
dynamic allocation of file space as well as sequential and random file access. Using this 
file system, a large number of programs can be stored in both source and machine- 
executable form. 


CP/M 2 is a high-performance, single console operating system that uses table-driven 
techniques to allow field reconfiguration to match a wide variety of disk capacities. All 
f 00 fundamental file restrictions are removed, maintaining upward compatibility from pre¬ 
vious versions of release 1. 


|M 


Features of CP/M 2 include field specification of one to sixteen logical drives, each 
containing up to eight megabytes. Any particular file can reach the full drive size with 
the capability of expanding to thirty-two megabytes in future releases. The directory 
size can be field-configured to contain any reasonable number of entries, and each file is 
optionally tagged with Read-Only and system attributes. Users of CP/M 2 are physical¬ 
ly separated by user numbers, with facilities for file copy operations from one user area 
to another. Powerful relative-record random access functions are present in CP/M 2 
that provide direct access to any of the 65536 records of an eight-megabyte file. 
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CP/M also supports ED, a powerful context editor, ASM™, an Intel-compatible 
assembler, and DDT™, debugger subsystems. Optional software includes a powerful 
Intel-compatible macro assembler, symbolic debugger, along with various high-level 
languages. When coupled with CP/M’s Console Command Processor (CCP), the result¬ 
ing facilities equal or exceed similar large computer facilities. 

CP/M is logically divided into several distinct parts: 

■ BIOS (Basic I/O System), hardware-dependent 

■ BDOS (Basic Disk Operating System) 

■ CCP (Console Command Processor) 

■ TPA (Transient Program Area) 

The BIOS provides the primitive operations necessary to access the disk drives and to 
interface standard peripherals: teletype, CRT, paper tape reader/punch, and user- 
defined peripherals. You can tailor peripherals for any particular hardware environ¬ 
ment by patching this portion of CP/M. The BDOS provides disk management by 
controlling one or more disk drives containing independent file directories. The BDOS 
implements disk allocation strategies that provide fully dynamic file construction while 
minimizing head movement across the disk during access. The BDOS has entry points 
that include the following primitive operations, which the program accesses: 

■ SEARCH looks for a particular disk file by name. 

■ OPEN opens a file for further operations. 

■ CLOSE closes a file after processing. 

■ RENAME changes the name of a particular file. 

■ READ reads a record from a particular file. 

■ WRITE writes a record to a particular file. 

■ SELECT selects a particular disk drive for further operations. 

The CCP provides a symbolic interface between your console and the remainder of 
the CP/M system. The CCP reads the console device and processes commands, which 
include listing the file directory, printing the contents of files, and controlling the 
operation of transient programs, such as assemblers, editors, and debuggers. The stan¬ 
dard commands that are available in the CCP are listed in Section 1.2.1. 

The last segment of CP/M is the area called the Transient Program Area (TPA). The 
TPA holds programs that are loaded from the disk under command of the CCP. During 
program editing, for example, the TPA holds the CP/M text editor machine code and 
data areas. Similarly, programs created under CP/M can be checked out by loading and 
executing these programs in the TPA. 
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Any or all of the CP/M component subsystems can be overlaid by an executing 
program. That is, once a user’s program is loaded into the TPA, the CCP, BDOS, and 
BIOS areas can be used as the program’s data area. A bootstrap loader is pro¬ 
grammatically accessible whenever the BIOS portion is not overlaid; thus, the user 
program need only branch to the bootstrap loader at the end of execution and the 
complete CP/M monitor is reloaded from disk. 

The CP/M operating system is partitioned into distinct modules, including the BIOS 
portion that defines the hardware environment in which CP/M is executing. Thus, the 
standard system is easily modified to any nonstandard environment by changing the 
peripheral drivers to handle the custom system. 

1.2 Functional Description 

You interact with CP/M primarily through the CCP, which reads and interprets 
commands entered through the console. In general, the CCP addresses one of several 
disks that are on-line. The standard system addresses up to sixteen different disk drives. 
These disk drives are labeled A through P. A disk is logged-in if the CCP is currently 
addressing the disk. To clearly indicate which disk is the currently logged disk, the CCP 
always prompts the operator with the disk name followed by the symbol >, indicating 
that the CCP is ready for another command. Upon initial start-up, the CP/M system is 
loaded from disk A, and the CCP displays the following message: 

CP/M VER x.x 

where x.x is the CP/M version number. All CP/M systems are initially set to operate in a 
20K memory space, but can be easily reconfigured to fit any memory size on the host 
system (see Section 1.6.9). Following system sign-on, CP/M automatically logs in disk 
A, prompts you with the symbol A>, indicating that CP/M is currently addressing disk 
A, and waits for a command. The commands are implemented at two levels: built-in 
commands and transient commands. 

1.2.1 General Command Structure 

Built-in commands are a part of the CCP program, while transient commands are 
loaded into the TPA from disk and executed. The following are built-in commands: 

■ ERA erases specified files. 

■ DIR lists filenames in the directory. 

■ REN renames the specified file. 

■ SAVE saves memory contents in a file. 

■ TYPE types the contents of a file on the logged disk. 
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Most of the commands reference a particular file or group of files. The form of a file 
reference is specified in Section 1.2.2. 

1.2.2 File References 

A file reference identifies a particular file or group of files on a particular disk 
attached to CP/M. These file references are either unambiguous (ufn) or ambiguous 
(afn). An unambiguous file reference uniquely identifies a single file, while an ambi¬ 
guous file reference is satisfied by a number of different files. 

File references consist of two parts: the primary filename and the filetype. Although 
the filetype is optional, it usually is generic. For example, the filetype ASM is used to 
denote that the file is an assembly language source file, while the primary filename 
distinguishes each particular source file. The two names are separated by a period, as 
shown in the following example: 

f i 1 e n a m e ♦ t '/ p 

In this example, filename is the primary filename of eight characters or less, and typ is 
the filetype of no more than three characters. As mentioned above, the name 

filename 

is also allowed and is equivalent to a filetype consisting of three blanks. The characters 
used in specifying an unambiguous file reference cannot contain any of the following 
special characters: 

= ?*[]%l()/\ 

while all alphanumerics and remaining special characters are allowed. 

An ambiguous file reference is used for directory search and pattern matching. The 
form of an ambiguous file reference is similar to an unambiguous reference, except the 
symbol ? can be interspersed throughout the primary and secondary names. In various 
commands throughout CP/M, the ? symbol matches any character of a filename in the ? 
position. Thus, the ambiguous reference 


X ? Z ♦ C ? M 
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matches the following unambiguous filenames 

XYZ.COM 

and 

X3Z♦CAM 

The * wildcard character can also be used in an ambiguous file reference. The * 
character replaces all or part of a filename or filetype. Note that 

* ♦ * 

equals the ambiguous file reference 
????????♦??? 
while 

filename** 

and 

* ♦ t y p 

are abbreviations for 

filename*??? 

and 

????????♦t v P 
respectively. As an example, 

A >0//? * # * 

is interpreted by the CCP as a command to list the names of all disk files in the 
directory. The following example searches only for a file by the name X.Y: 

b>DIRX,Y 
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Similarly, the command 
A >DIR X?Y* C?M 

causes a search for all unambiguous filenames on the disk that satisfy this ambiguous 
reference. 


The following file references are valid unambiguous file references: 


X 

X ♦ Y 
XYZ 

XYZ.COM 
GAMMA 
GAMMA. 1 

As an added convenience, the programmer can generally specify the disk drive name 
along with the filename. In this case, the drive name is given as a letter A through P 
followed by a colon (:). The specified drive is then logged-in before the file operation 
occurs. Thus, the following are valid file references with disk name prefixes: 


A : X . Y 
P:XYZ♦COM 
B: XYZ 
B:X♦A?M 
C:GAMMA 
C:*.ASM 

All alphabetic lower-case letters in file and drive names are translated to upper-case 
when they are processed by the CCP. 
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1.3 Switching Disks 

The operator can switch the currently logged disk by typing the disk drive name, A 
through P, followed by a colon when the CCP is waiting for console input. The 
following sequence of prompts and commands can occur after the CP/M system is 
loaded from disk A: 

CP/M VER 2 ♦ 2 
A >DIR 

A : SAMPLE ASM SAMPLE PRN 
A >B: 

B >DIR*.ASM 
B s DUMP ASM FILES ASM 
b> A : 

1.4 Built-in Commands 

The file and device reference forms described can now be used to fully specify the 
structure of the built-in commands. Assume the following abbreviations in the descrip¬ 
tion below: 

ufn unambiguous file reference 

afn ambiguous file reference 

Recall that the CCP always translates lower-case characters to upper-case characters 
internally. Thus, lower-case alphabetics are treated as if they are upper-case in com¬ 
mand names and file references. 


List all files on disk A. 

Switch to disk B. 

List all ASM files on B. 

Switch back to A. 
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1.4.1 ERA Command 

Syntax: 


ERA afn 


The ERA (erase) command removes files from the currently logged-in disk, for 
example, the disk name currently prompted by CP/M preceding the >. The files that are 
erased are those that satisfy the ambiguous file reference afn. The following examples 
illustrate the use of ERA: 


ERA X♦Y 


ERA ><♦* 


The file named X ♦ Y on the currently logged disk is 
removed from the disk directory and the space is 
returned. 

All files with primary name X are removed from the 
current disk. 


ERA *♦ ASM 


All files with secondary name ASM are removed from 
the current disk. 


ERA X?Y ♦ C?M 

ERA * ♦ * 


ERA b : * ♦ PRN 


All files on the current disk that satisfy the ambiguous 
reference X?Y ♦ C?M are deleted. 

Erase all files on the current disk. In this case, the 
CCP prompts the console with the message 

ALL FILES (Y/N>? 

which requires a Y response before files are actually 
removed. 

All files on drive B that satisfy the ambiguous refer¬ 
ence ???????? ♦ PRN are deleted, independently 
of the currently logged disk. 
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1.4.2 


DIR Command 




Syntax: 

DIR afn 

The DIR (directory) command causes the names of all files that satisfy the ambiguous 
filename afn to be listed at the console device. As a special case, the command 

DIR 


lists the files on the currently logged disk (the command DIR is equivalent to the 
command DIR***). The following are valid DIR commands: 


DIR X ♦ Y 
DIR X?Z*C?M 
DIR ??♦Y 


Similar to other CCP commands, the afn can be preceded by a drive name. The 
following DIR commands cause the selected drive to be addressed before the directory 
search takes place: 


JUSSI 


DIR B: 

DIR B:X,Y 
DIR B:**A?M 

• 

If no files on the selected disk satisfy the directory request, the message NO FILE 
appears at the console. 


bhi 
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mm, 

1.4.3 REN Command 

Syntax: 

REN ufnl =ufn2 

The REN (rename) command allows you to change the names of files on disk. The 
file satisfying ufn2 is changed to ufnl. The currently logged disk is assumed to contain 
the file to rename (ufn2). You can also type a left-directed arrow instead of the equal 
sign if the console supports this graphic character. The following are examples of the 
REN command: 


REN X * Y = 0 * R The fileO ♦ R is changed to X ♦ Y . ^ 

REN XYZ ♦ C0M = XYZ ♦ XXX The file XYZ ♦ XXX is changed to 

XYZ.COM. -p* 


The operator precedes either ufnl or ufn2 (or both) by an optional drive address. If 
ufnl is preceded by a drive name, then ufn2 is assumed to exist on the same drive. 
Similarly, if ufn2 is preceded by a drive name, then ufnl is assumed to exist on the drive 
as well. The same drive must be specified in both cases if both ufnl and ufn2 are 
preceded by drive names. The following REN commands illustrate this format: 

REN A: X ♦ ASM = Y s ASM The file Y ♦ ASM is changed to X . ASM on 

drive A. 


REN B:ZAP.BAS=Z0T.BAS 


The fileZOT.BAS is changed to ZAP»BASon 
drive B. 




REN B:A♦ASM = B s A♦BAK 


The file A. BAK is renamed to A .ASM on 
drive B. 


If ufnl is already present, the REN command responds with the error FILE EX- mm ' : 
I STS and not perform the change. If ufn2 does not exist on the specified disk, the 
message NO FILE is printed at the console. 
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1.4.4 SAVE Command 


. Syntax: 

MM —- 

SAVE n ufn 


F** The SAVE command places n pages (256-byte blocks) onto disk from the TP A and 
names this file ufn. In the CP/M distribution system, the TPA starts at 100H (hexade¬ 
cimal) which is the second page of memory. The SAVE command must specify 2 pages 
of memory if the user’s program occupies the area from 100H through 2FFH. The 
machine code file can be subsequently loaded and executed. The following are exam¬ 
ples of the SAVE command: 




SAME 3X ♦ COM 


Copies 100H through 3FFH to X ♦ COM . 


SAVE 40 0 


Copies 100H through 28FFH to 0. Note that 28 is 
the page count in 28FFH, and that 28H = 2* 

16 + 8 = 40 decimal. 


SAVE 4 X ♦ Y 


Copies 100H through 4FFH to X ♦ Y. 




The SAVE command can also specify a disk drive in the ufn portion of the command, as 
shown in the following example: 


SAVE 10 B : ZOT • COM 


1.4.5 TYPE Command 


Copies 10 pages, 100H through OAFFH, to the file 
ZOT • COM on drive B. 


Syntax: 


TYPE ufn 




The TYPE command displays the content of the ASCII source file ufn on the current¬ 
ly logged disk at the console device. The following are valid TYPE commands: 


TYPE X«Y 
TYPE X.PLM 
TYPE XXX 
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The TYPE command expands tabs, CTRL-I characters, assuming tab positions are 
set at every eighth column. The ufn can also reference a drive name. 

TYPE B: X ♦ P R N The file X ♦ P R N from drive B is displayed. 



1.4.6 USER Command 
Syntax: 

USER n ^ 


The USER command allows maintenance of separate files in the same directory. In 
the syntax line, n is an integer value in the range 0 to 15. On cold start, the operator is 
automatically logged into user area number 0, which is compatible with standard 
CP/M 1 directories. You can issue the USER command at any time to move to another 
logical area within the same directory. Drives that are logged-in while addressing one gp^ 
user number are automatically active when the operator moves to another. A user 
number is simply a prefix that accesses particular directory entries on the active disks. 

The active user number is maintained until changed by a subsequent USER com- 
mand, or until a cold start when user 0 is again assumed. 


1.5 Line Editing and Output Control 



The CCP allows certain line-editing functions while typing command lines. The 
CTRL-key sequences are obtained by pressing the control and letter keys simultaneous¬ 
ly. Further, CCP command lines are generally up to 255 characters in length; they are 
not acted upon until the carriage return key is pressed. 


Table 1-1. Line-editing Control Characters 

Character Meaning 

CTRL-C Reboots CP/M system when pressed at start of line. 

CTRL-E Physical end of line; carriage is returned, but line is not sent 
until the carriage return key is pressed. 

CTRL-H Backspaces one character position. 
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Table 1-1. (continued) 


Character 

Meaning 

CTRL-J 

Terminates current input (line-feed). 

CTRL-M 

Terminates current input (carriage return). 

CTRL-P 

Copies all subsequent console output to the currently assigned 
list device (see Section 1.6.1). Output is sent to the list device 
and the console device until the next CTRL-P is pressed. 

CTRL-R 

Retypes current command line; types a clean line following 
character deletion with rubouts. 

CTRL-S 

Stops the console output temporarily. Program execution and 
output continue when you press any character at the console, 
for example another CTRL-S. This feature stops output on 
high speed consoles, such as CRTs, in order to view a segment 
of output before continuing. 

CTRL-U 

Deletes the entire line typed at the console. 

CTRL-X 

Same as CTRL-U. 

CTRL-Z 

Ends input from the console (used in PIP and ED). 

rub/del 

Deletes and echoes the last character typed at the console. 
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1.6 Transient Commands 

Transient commands are loaded from the currently logged disk and executed in the 
TPA. The transient commands for execution under the CCP are below. Additional 
functions are easily defined by the user (see Section 1.6.3). 


Table 1-2. CP/M Transient Commands 


Command 

Function 

STAT 

Lists the number of bytes of storage remaining on the current¬ 
ly logged disk, provides statistical information about particu¬ 
lar files, and displays or alters device assignment. 

ASM 

Loads the CP/M assembler and assembles the specified pro¬ 
gram from disk. 

LOAD 

Loads the file in Intel HEX machine code format and pro¬ 
duces a file in machine executable form which can be loaded 
into the TPA. This loaded program becomes a new command 
under the CCP. 

DDT 

Loads the CP/M debugger into TPA and starts execution. 

PIP 

Loads the Peripheral Interchange Program for subsequent 
disk file and peripheral transfer operations. 

ED 

Loads and executes the CP/M text editor program. 

SYSGEN 

Creates a new CP/M system disk. 

SUBMIT 

Submits a file of commands for batch processing. 

DUMP 

Dumps the contents of a file in hex. 

MOVCPM 

Regenerates the CP/M system for a particular memory size. 


i*^ 






Will 
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Transient commands are specified in the same manner as built-in commands, and 
additional commands are easily defined by the user. For convenience, the transient 
command can be preceded by a drive name which causes the transient to be loaded 
from the specified drive into the TPA for execution. Thus, the command 

B:STAT 

causes CP/M to temporarily log in drive B for the source of the STAT transient, and 
then return to the original logged disk for subsequent processing. 

1.6.1 STAT Command 

Syntax: 

STAT 

STAT “command line” 

The STAT command provides general statistical information about file storage and 
device assignment. Special forms of the command line allow the current device assign¬ 
ment to be examined and altered. The various command lines that can be specified are 
shown with an explanation of each form to the right. 

STAT If you type an empty command line, the STAT transient calcu¬ 

lates the storage remaining on all active drives, and prints one of 
the following messages: 

d: R/N i SPACE: nnnK 

d: R /□t SPACE: nnnK 

for each active drive d:, where R/W indicates the drive can be 
read or written, and R/O indicates the drive is Read-Only (a 
drive becomes R/O by explicitly setting it to Read-Only, as 
shown below, or by inadvertently changing disks without per¬ 
forming a warm start). The space remaining on the disk in drive 
d: is given in kilobytes by nnn. 

STAT d: If a drive name is given, then the drive is selected before the 

storage is computed. Thus, the command STAT B: could be 
issued while logged into drive A, resulting in the message 

BYTES REMAINING ON B: nnnK 
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STAT afn The command line can also specify a set of files to be scanned by 

STAT. The files that satisfy afn are listed in alphabetical order, 
with storage requirements for each file under the heading: 

RECS BYTES EXT DsFILENAME♦TYP 
rrrr bbbK ee d:filename*typ 


where rrrr is the number of 128-byte records allocated to the file, 
bbb is the number of kilobytes allocated to the file 
(bbb = rrrr* 128/1024), ee is the number of 16K extensions 
(ee = bbb/16), d is the drive name containing the file (A...P), 
filename is the eight-character primary filename, and typ is the - m .. 
three-character filetype. After listing the individual files, the stor¬ 
age usage is summarized. 

STAT d:afn The drive name can be given ahead of the afn. The specified drive IS "^ 

is first selected, and the form STAT afn is executed. 


STAT d: = R/O This form sets the drive given by d to Read-Only, remaining in 
effect until the next warm or cold start takes place. When a disk 
is Read-Only, the message 

BOOS ERR ON d: Read-Only 






appears if there is an attempt to write to the Read-Only disk. 

CP/M waits until a key is pressed before performing an automa¬ 
tic warm start, at which time the disk becomes R/W. 

The STAT command allows you to control the physical-to-logical device assignment. fe9B ^ 
See the IOBYTE function described in Sections 5 and 6. There are four logical peripher¬ 
al devices that are, at any particular instant, each assigned one of several physical 
peripheral devices. The following is a list of the four logical devices: 


■ CON: is the system console device, used by CCP for communication with the 
operator. 

■ RDR: is the paper tape reader device. 

■ PUN: is the paper tape punch device. 

■ LST: is the output list device. 







1-16 


m DIGITAL RESEARCH 



CP/M Operating System Manual 


1.6 Transient Commands 




The actual devices attached to any particular computer system are driven by sub¬ 
routines in the BIOS portion of CP/M. Thus, the logical RDR: device, for example, 
could actually be a high speed reader, teletype reader, or cassette tape. To allow some 
flexibility in device naming and assignment, several physical devices are defined in 
Table 1-3. 




mm 

I 




Table 1-3. Physical Devices 


Device 

Meaning 


TTY: 

Teletype device (slow speed console) 

pwl 

CRT: 

Cathode ray tube device (high speed console) 


BAT: 

Batch processing (console is current RDR:, 


output goes to current LST: device) 


UC1: 

User-defined console 


PTR: 

Paper tape reader (high speed reader) 

ppi 

UR1: 

User-defined reader #1 


UR2: 

User-defined reader #2 


PTP: 

Paper tape punch (high speed punch) 


UP1: 

User-defined punch #1 


UP2: 

User-defined punch #2 

jSPW 

LPT: 

Line printer 


UL1: 

User-defined list device #1 
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It is emphasized that the physical device names might not actually correspond to 
devices that the names imply. That is, you can implement the PTP: device as a cassette 
write operation. The exact correspondence and driving subroutine is defined in the 
BIOS portion of CP/M. In the standard distribution version of CP/M, these devices 
correspond to their names on the MDS 800 development system. 

The command, 


STAT UAL: 

produces a summary of the available status commands, resulting in the output: 




Temp R/0 DisK d:$R/0 ^ 

Set Indicator: fi1ename♦typ $R/0 $R/W $SYS $DIR 
DisK Status: DSK: d:DSK 
I o b y t e Assign: 

which gives an instant summary of the possible STAT commands and shows the 
permissible logical-to-physical device assignments: 


CON:=TTY:CRT:BAT:UC1: 
RDR:=TTY:PTR:UR1:UR2: 
PUN:=TTY:PTP:UP1:UP2: 
LST:=TTY:CRT:LPT:UL1 : 


The logical device to the left takes any of the four physical assignments shown to the 
right. The current logical-to-physical mapping is displayed by typing the command: 


STAT DEV: 




This command produces a list of each logical device to the left and the current corres¬ 
ponding physical device to the right. For example, the list might appear as follows: 


CON:=CRT 
RDR:=UR1 
PUN:=PTP 
LST:=TTY 
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The current logical-to-physical device assignment is changed by typing a STAT com¬ 
mand of the form: 

STAT ldl = pdl, ld2 = pd2,. . . , ldn = pdn 


where ldl through ldn are logical device names and pdl through pdn are compatible 
physical device names. For example, ldl and pdl appear on the same line in the VAL: 
command shown above. The following example shows valid STAT commands that 
change the current logical-to-physical device assignments: 


STAT CON:=CRT: 

STAT PUN:=TTY: ,LST:=LPT: >RDR:=TTY s 
The command form, 


p® 1 STAT d:filename.typ $S 


where d: is an optional drive name and filename.typ is an unambiguous or ambiguous 
filename, produces the following output display format: 


|M 

pppf 


Size 

Rees 

Bytes 

Ext Ac c 

48 

48 

GK 

1 R/0 A:ED♦COM 

55 

55 

12K 

1 R/0 (A:PIP♦COM ) 

G553G 

128 

1 GK 

2 R/W A:X♦DAT 


where the $S parameter causes the Size field to be displayed. Without the $S, the Size 
field is skipped, but the remaining fields are displayed. The Size field lists the virtual file 
size in records, while the Rees field sums the number of virtual records in each extent. 
For files constructed sequentially, the Size and Rees fields are identical. The Bytes field 
lists the actual number of bytes allocated to the corresponding file. The minimum 
allocation unit is determined at configuration time; thus, the number of bytes corres¬ 
ponds to the record count plus the remaining unused space in the last allocated block 
for sequential files. Random access files are given data areas only when written, so the 
Bytes field contains the only accurate allocation figure. In the case of random access, the 
Size field gives the logical end-of-file record position and the Rees field counts the 
logical records of each extent. Each of these extents, however, can contain unallocated 
holes even though they are added into the record count. 
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The Ext field counts the number of physical extents allocated to the file. The Ext 
count corresponds to the number of directory entries given to the file. Depending on 
allocation size, there can be up to 128K bytes (8 logical extents) directly addressed by a 
single directory entry. In a special case, there are actually 256K bytes that can be 
directly addressed by a physical extent. 


The Acc field gives the R/O or R/W file indicator, which you can change using the 
commands shown. The four command forms, 


STAT difilename.typ $R/0 
STAT d.-filename.typ $R/W 
STAT d:filename.typ $SYS 
STAT d:filename.typ $DIR 





set or reset various permanent file indicators. The R/O indicator places the file, or set of 
files, in a Read-Only status until changed by a subsequent STAT command. The R/O 
status is recorded in the directory with the file so that it remains R/O through interven¬ 
ing cold start operations. The R/W indicator places the file in a permanent Read-Write 
status. The SYS indicator attaches the system indicator to the file, while the DIR 
command removes the system indicator. The filename.typ may be ambiguous or un¬ 
ambiguous, but files whose attributes are changed are listed at the console when the 
change occurs. The drive name denoted by d: is optional. 
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When a file is marked R/O, subsequent attempts to erase or write into the file 
produce the following BDOS message at your screen: 

BDOS Err on d: File R/0 

lists the drive characteristics of the disk named by d: that is in the range A:, 

The drive characteristics are listed in the following format: 


d 

D r i 

u 

e 

C 

har 

a c 

t e 

r 

i si 

l i c 

s 


G5536 

128 


B 

Y t 

e R 
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o r 

d 

C« 
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c 

i t y 

8192 

Ki 1 

0 
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y t 

e D 

r i 
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Cat 

=>ac 
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t y 

128 

32 

B 

y 

t e 

Di 

re 

c t 

0 

r y 

En 
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ries 

0 

Che 

c 

K 

e d 

Di 

r e 

c t 

0 

ry 

Eri 
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1024 

Re c 
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d s 

/Ex 
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n t 






128 

Re c 

0 

r 

d s 

/ B 1 

o c 

k 






58 

Sec 

t 

0 

rs 

/Tr 

ac 

K 






2 

Res 

e 

r 

u e 

d T 

ra 

c k 

5 






where d: is the selected drive, followed by the total record capacity (65536 is an 
eight-megabyte drive), followed by the total capacity listed in kilobytes. The directory 
size is listed next, followed by the checked entries. The number of checked entries is 
usually identical to the directory size for removable media, because this mechanism is 
used to detect changed media during CP/M operation without an intervening warm 
start. For fixed media, the number is usually zero, because the media are not changed 
without at least a cold or warm start. 

The number of records per extent determines the addressing capacity of each direc¬ 
tory entry (1024 times 128 bytes, or 128K in the previous example). The number of 
records per block shows the basic allocation size (in the example, 128 records/block 
times 128 bytes per record, or 16K bytes per block). The listing is then followed by the 
number of physical sectors per track and the number of reserved tracks. 
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For logical drives that share the same physical disk, the number of reserved tracks 
can be quite large because this mechanism is used to skip lower-numbered disk areas 
allocated to other logical disks. The command form 

STAT DSK : 

produces a drive characteristics table for all currently active drives. The final STAT 
command form is 

STATUSR: 


which produces a list of the user numbers that have files on the currently addressed 
disk. The display format is 

Active User: 0 
A c t i v e F i 1 e s : 0 1 3 


where the first line lists the currently addressed user number, as set b> the last CCP 
USER command, followed by a list of user numbers scanned from the current directory, mms(_ 
In this case, the active user number is 0 (default at cold start) with three user numbers 
that have active files on the current disk. The operator can subsequently examine the 
directories of the other user numbers by logging in with USER 1 or USER 3 commands, p— 
followed by a DIR command at the CCP level. 


1.6.2 ASM Command 
Syntax: 




ASM ufn 




The ASM command loads and executes the CP/M 8080 assembler. The ufn specifies 
a source file containing assembly language statements, where the filetype is assumed to 
be ASM and is not specified. The following ASM commands are valid: 


ASM X 
ASM GAMMA 

The two-pass assembler is automatically executed. Assembly errors that occur during 
the second pass are printed at the console. 
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The assembler produces a file: 

X ♦ PRN 

where X is the primary name specified in the ASM command. The PRN file contains a 
listing of the source program with embedded tab characters if present in the source 
program, along with the machine code generated for each statement and diagnostic 
error messages, if any. The PRN file is listed at the console using the TYPE command, 
or sent to a peripheral device using PIP (see Section 1.6.4). Note that the PRN file 
contains the original source program, augmented by miscellaneous assembly informa¬ 
tion in the leftmost 16 columns; for example, program addresses and hexadecimal 
machine code. The PRN file serves as a backup for the original source file. If the source 
file is accidentally removed or destroyed, the PRN file can be edited by removing the 
leftmost 16 characters of each line (see Section 2). This is done by issuing a single editor 
macro command. The resulting file is identical to the original source file and can be 
renamed from PRN to ASM for subsequent editing and assembly. The file 

X.HEX 

is also produced, which contains 8080 machine language in Intel HEX format suitable 
for subsequent loading and execution (see Section 1.6.3). For complete details of 
CP/M’s assembly language program, see Section 3. 

The source file for assembly is taken from an alternate disk by prefixing the assembly 
language filename by a disk drive name. The command 

t 

ASM B 5 ALPHA 

loads the assembler from the currently logged drive and processes the source program 
ALPHA*ASM on drive B. The HEX and PRN files are also placed on drive B in this 
case. 
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1.6.3 LOAD Command 

Syntax: 

LOAD ufn 

The LOAD command reads the file ufn, which is assumed to contain HEX format 
machine code, and produces a memory image file that can subsequently be executed. 
The filename ufn is assumed to be of the form: 

X.HEX 





and only the filename X need be specified in the command. The LOAD command mm 
creates a file named 


X.COM 


that marks it as containing machine executable code. The file is actually loaded into 
memory and executed when the user types the filename X immediately after the 
prompting character > printed by the CCP. 


Generally, the CCP reads the filename X following the prompting character and 
looks for a built-in function name. If no function name is found, the CCP searches the 
system disk directory for a file by the name 


X ♦ COM MH§i 

If found, the machine code is loaded into the TPA, and the program executes. Thus, the 
user need only LOAD a hex file once; it can be subsequently executed any number of 
times by typing the primary name. This way, you can invent new commands in the 
CCP. Initialized disks contain the transient commands as COM files, which are 
optionally deleted. The operation takes place on an alternate drive if the filename is 
prefixed by a drive name. Thus, 


LOAD B:BETA 

brings the LOAD program into the TPA from the currently logged disk and operates on 
drive B after execution begins. 
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Note: the BETA.HEX file must contain valid Intel format hexadecimal machine code 
records (as produced by the ASM program, for example) that begin at 100H of the 
TPA. The addresses in the hex records must be in ascending order; gaps in unfilled 
memory regions are filled with zeroes by the LOAD command as the hex records are 
read. Thus, LOAD must be used only for creating CP/M standard COM files that 
operate in the TPA. Programs that occupy regions of memory other than the TPA are 
loaded under DDT. 

1.6.4 PIP 

Syntax: 

PIP 

PIP destination = source# 1, source#2,. . ., source #n 

PIP is the CP/M Peripheral Interchange Program that implements the basic media 
conversion operations necessary to load, print, punch, copy, and combine disk files. 
The PIP program is initiated by typing one of the following forms: 

PIP 

PIP command line 

In both cases PIP is loaded into the TPA and executed. In the first form, PIP reads 
command lines directly from the console, prompted with the * character, until an 
empty command line is typed (for example, a single carriage return is issued by the 
operator). Each successive command line causes some media conversion to take place 
according to the rules shown below. 

In the second form, the PIP command is equivalent to the first, except that the single 
command line given with the PIP command is automatically executed, and PIP termi¬ 
nates immediately with no further prompting of the console for input command lines. 
The form of each command line is 

destination = source# 1, source#2,. . ., source#n 

where destination is the file or peripheral device to receive the data, and source# 1,. . ., 
source#n is a series of one or more files or devices that are copied from left to right to 
the destination. 
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When multiple files are given in the command line (for example, n>l), the individual 
files are assumed to contain ASCII characters, with an assumed CP/M end-of-file 
character (CTRL-Z) at the end of each file (see the O parameter to override this 
assumption). Lower-case ASCII alphabetics are internally translated to upper-case to 
be consistent with CP/M file and device name conventions. Finally, the total command 
line length cannot exceed 255 characters. CTRL-E can be used to force a physical 
carriage return for lines that exceed the console width. 


The destination and source elements are unambiguous references to CP/M source 
files with or without a preceding disk drive name. That is, any file can be referenced 
with a preceding drive name (A: through P:) that defines the particular drive where the 
file can be obtained or stored. When the drive name is not included, the currently 
logged disk is assum^. The destination file can also appear as one or more of the 
source files; in which case the source file is not altered until the entire concatenation is 
complete. If it already exists, the destination file is removed if the command line is 
properly formed. It is not removed if an error condition arises. The following command 
lines, with explanations to the right, are valid as input to PIP: 


X = Y 


X = Y tZ 


Copies to file X from file Y, where X and Y are 
unambiguous filenames; Y remains unchanged. 

Concatenates files Y and Z and copies to file X, with 
Y and Z unchanged. 


X*ASM = Y*ASM>Z.ASM Creates the file X ♦ ASM from the concatenation of the 

Y and Z. ASM files. 


NEW ♦ ZOT = B : OLD ♦ ZAP Moves a copy of OLD* ZAP from drive B to the 

currently logged disk; names the file NEW ♦ ZOT. 

B:A*U = B:B*V >A:C*W>D*X Concatenates file B*V from drive B with C*W from 

drive A and D ♦ X from the logged disk; creates the file 
A.U on drive B. 
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pm 


For convenience, PIP allows abbreviated commands for transferring files between 
disk drives. The abbreviated PIP forms are 

PIP d: = afn 
PIP d, =d 2 :afn 
PIP ufn = d 7 : 

PIP d, :ufn = d 2 : 


— The first form copies all files from the currently logged disk that satisfy the afn to the 
' same files on drive d, where d = A. . .P. The second form is equivalent to the first, 
where the source for the copy is drive d 2 , where d 2 = A. . .P. The third form is 
equivalent to the command PIP d!:ufn = d 2 :ufn which copies the file given by ufn from 
drive d 2 to the file ufn on drive The fourth form is equivalent to the third, where the 
source disk is explicitly given by d 2 :. 


P® 1 The source and destination disks must be different in all of these cases. If an afn is 
“ specified, PIP lists each ufn that satisfies the afn as it is being copied. If a file exists by 
the same name as the destination file, it is removed after successful completion of the 
pm copy and replaced by the copied file. 

The following PIP commands give examples of valid disk-to-disk copy-operations: 




B = * ♦COM 


Copies all files that have the secondary name COM 
to drive B from the current drive. 


,f« A : =B : ZAP ♦ * 


Copies all files that have the primary name ZAP to 
drive A from drive B. 


j*®* ZAP ♦ ASM = B : 

B:ZOT♦C0M=A: 
L B:=GAMMA♦BAS 


B:=A:GAMMA♦BAS 


Same as ZAP . ASM = B : ZAP . ASM 
Same as B:ZOT.COM = A:ZOT.COM 
Same as B : GAMMA . BAS = GAMMA.BAS 
Same as B : GAMMA . BAS = A : GAMMA . BAS 
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PIP allows reference to physical and logical devices that are attached to the CP/M 
system. The device names are the same as given under the STAT command, along with 
a number of specially named devices. The following is a list of logical devices given in 
the STAT command 


CON: (console) 

RDR: (reader) 

PUN: (punch) 

LST: (list) 

while the physical devices are 


TTY: (console , reader, punch, or list) 

CRT: (console, or list), UC1: (console) 

PTR: (reader), UR1: (reader), UR2: (reader) 

PTP: (punch), UP1: (punch), UP2: (punch) 

LPT: (list), UL1: (list) 


The BAT: physical device is not included, because this assignment is used only to 
indicate that the RDR: and LST: devices are used for console input/output. 

The RDR, LST, PUN, and CON devices are all defined within the BIOS portion of 
CP/M, and are easily altered for any particular I/O system. The current physical device 
mapping is defined by IOBYTE; see Section 6 for a discussion of this function. The 
destination device must be capable of receiving data, for example, data cannot be sent 
to the punch, and the source devices must be capable of generating data, for example, 
the LST: device cannot be read. 


The following list describes additional device names that can be used in PIP com¬ 
mands. 


■ NUL: sends 40 nulls (ASCII Os) to the device. This can be issued at the end of 
punched output. 

■ EOF: sends a CP/M end-of-file (ASCII CTRL-Z) to the destination device (sent 
automatically at the end of all ASCII data transfers through PIP). 

■ INP: is a special PIP input source that can be patched into the PIP program. PIP 
gets the input data character-by-character, by CALLing location 103H, with 
data returned in location 109H (parity bit must be zero). 


1-28 


m DIGITAL RESEARCH"' 



1.6 Transient Commands 




CP/M Operating System Manual 


■ OUT: is a special PIP output destination that can be patched into the PIP 
program. PIP CALLs location 106H with data in register C for each character to 
transmit. Note that locations 109H through 1FFH of the PIP memory image are 
not used and can be replaced by special purpose drivers using DDT (see Section 

4). 

■ PRN: is the same as LST:, except that tabs are expanded at every eighth charac¬ 
ter position, lines are numbered, and page ejects are inserted every 60 lines with 
an initial eject (same as using PIP options [t8np]). 

File and device names can be interspersed in the PIP commands. In each case, the 
specific device is read until end-of-file (CTRL-Z for ASCII files, and end-of-data for 
non-ASCII disk files). Data from each device or file are concatenated from left to right 
until the last data source has been read. 


The destination device or file is written using the data from the source files, and an 
P" 1 end-of-file character, CTRL-Z, is appended to the result for ASCII files. If the destina¬ 
tion is a disk file, ja temporary file is created ($$$ secondary name) that is changed to 
the actual filename only on successful completion of the copy. Files with the extension 
COM are always assumed to be non-ASCII. 

The copy operation can be aborted at any time by pressing any key on the keyboard, 
pm PIP responds with the message ABORTED to indicate that the operation has not been 
completed. If any operation is aborted, or if an error occurs during processing, PIP 
removes any pending commands that were set up while using the SUBMIT command. 

PIP performs a special function if the destination is a disk file with type HEX (an Intel 
hex-formatted machine code file), and the source is an external peripheral device, such 
as a paper tape reader. In this case, the PIP program checks to ensure that the source file 
contains a properly formed hex file, with legal hexadecimal values and checksum 
records. 


|ipm 


When an invalid input record is found, PIP reports an error message at the console 
and waits for corrective action. Usually, you can open the reader and rerun a section of 
the tape (pull the tape back about 20 inches). When the tape is ready for the reread, a 
single carriage return is typed at the console, and PIP attempts another read. If the tape 
position cannot be properly read, continue the read by typing a return following the 
error message, and enter the record manually with the ED program after the disk file is 
constructed. 

PIP allows the end-of-file to be entered from the console if the source file is an RDR: 
device. In this case, the PIP program reads the device and monitors the keyboard. If 
CTRL-Z is typed at the keyboard, the read operation is terminated normally. 
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The following are valid PIP commands: 

PIP LST: =><♦ PRN 

Copies X.PRN to the LST device and terminates the PIP program. 

PIP 








Starts PIP for a sequence of commands. PIP prompts with 
*CON:-X,ASM,Y,ASM,Z.ASM 

Concatenates three ASM files and copies to the CON device. 

* X ♦ HEX=CON: *Y* HEXtPTR: 

Creates a HEX file by reading the CON until a CTRL-Z is typed, 
followed by data from Y.HEX and PTR until a CTRL-Z is encoun¬ 
tered. 


PIP PUN: =NUL: *)< ♦ ASM #EOF: >NUL : 


Sends 40 nulls to the punch device; copies the X.ASM file to the 
punch, followed by an end-of-file, CTRL-Z, and 40 more null charac¬ 
ters. 




(carriage return) 


A single carriage return stops PIP. 

You can also specify one or more PIP parameters, enclosed in left and right square 
brackets, separated by zero or more blanks. Each parameter affects the copy operation, 
and the enclosed list of parameters must immediately follow the affected file or device. 
Generally, each parameter can be followed by an optional decimal integer value (the S 
and Q parameters are exceptions). Table 1-4 describes valid PIP parameters. 
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Table 1-4. PIP Parameters 


Parameter 

Meaning 

B 

Blocks mode transfer. Data are buffered by PIP until an ASCII x-off 
character, CTRL-S, is received from the source device. This allows 
transfer of data to a disk file from a continuous reading device, such 
as a cassette reader. Upon receipt of the x-off, PIP clears the disk 
buffers and returns for more input data. The amount of data that can 
be buffered depends on the memory size of the host system. PIP 
issues an error message if the buffers overflow. 

Dn 

Deletes characters that extend past column n in the transfer of data 
to the destination from the character source. This parameter is gener¬ 
ally used to truncate long lines that are sent to a narrow printer or 
console device. 

E 

Echoes all transfer operations to the console as they are being per¬ 
formed. 

F 

Filters form-feeds from the file. All embedded form-feeds are re¬ 
moved. The P parameter can be used simultaneously to insert new 
form-feeds. 

Gn 

Gets file from user number n (n in the range 0-15). 

H 

Transfers HEX data. All data are checked for proper Intel hex file 
format. Nonessential characters between hex records are removed 
during the copy operation. The console is prompted for corrective 
action in case errors occur. 

I 

Ignores :00 records in the transfer of Intel hex format file. The I 
parameter automatically sets the H parameter. 

L 

Translates upper-case alphabetics to lower-case. 

N 

Adds line numbers to each line transferred to the destination, starting 
at one and incrementing by 1. Leading zeroes are suppressed, and the 
number is followed by a colon. If N2 is specified, leading zeroes are 
included and a tab is inserted following the number. The tab is 
expanded if T is set. 


m DIGITAL RESEARCH ,u 


1-31 




1.6 Transient Commands 


CP/M Operating System Manual 


Table 1-4. (continued) 


Parameter 

Meaning 

O 

Transfers non-ASCII object files. The normal CP/M end-of-file is 
ignored. 

Pn 

Includes page ejects at every n lines with an initial page eject. If n = 1 
or is excluded altogether, page ejects occur every 60 lines. If the F 
parameter is used, form-feed suppression takes place before the new 
page ejects are inserted. 

QstZ 

Quits copying from the source device or file when the string s, ter¬ 
minated by CTRL-Z, is encountered. 

R 

Reads system files. 

SsTZ 

Start copying from the source device when the string s, terminated by 
CTRL-Z, is encountered. The S and Q parameters can be used to 
abstract a particular section of a file, such as a subroutine. The start 
and quit strings are always included in the copy operation. 


If you specify a command line after the PIP command keyword, the 
CCP translates strings following the S and Q parameters to upper¬ 
case. If you do not specify a command line, PIP does not perform the 
automatic upper-case translation. 

Tn 

Expands tabs, CTRL-I characters, to every nth column during the 
transfer of characters to the destination from the source. 

U 

Translates lower-case alphabetics to upper-case during the copy op¬ 
eration. 

V 

Verifies that data have been copied correctly by rereading after the 
write operation (the destination must be a disk file). 

w 

Writes over R/O files without console interrogation. 

z 

Zeros the parity bit on input for each ASCII character. 
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The following examples show valid PIP commands that specify parameters in the file 
transfer. 

PIP X♦ ASM = Bs[u] 

Copies X ♦ ASM from drive B to the current drive and verifies that the 
data were properly copied. 

PIP LPT:= X♦A S M[n 18 u] 

Copies X ♦ ASM to the LPT: device; numbers each line, expands tabs to 
every eighth column, and translates lower-case alphabetics to upper¬ 
case. 


PIP P U N : = X ♦ H E X [ i ] OCZOTEh] 


First copies X ♦ HEX to the PUN: device and ignores the trailing :00 
record in X ♦ HEX; continues the transfer of data by reading Y ♦ ZOT, 
which contains HEX records, including any :00 records it contains. 

PIP X ♦ L I B = Y ♦ A S M E s S U B R 1 sTzpJMP L3tz] 

Copies from the file Y ♦ ASM into the file X ♦ L IB. The command starts 
the copy when the string SUBR 1 ; has been found, and quits copying 
after the string JMP L3 is encountered. 


PIP PRN:= X♦ASM[p50] 


Sends X ♦ ASM to the LST: device with line numbers, expands tabs to 
every eighth column, and ejects pages at every 50th line. The assumed 
parameter list for a PRN file is nt8p60; p50 overrides the default 
value. 

Under normal operation, PIP does not overwrite a file that is set to a permanent R/O 
status. If an attempt is made to overwrite an R/O file, the following prompt appears: 

DESTINATION FILE IS R/O > DELETE (Y/N>? 

If you type Y, the file is overwritten. Otherwise, the following response appears: 

** NOT DELETED ** 
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The file transfer is skipped, and PIP continues with the next operation in sequence. To 
avoid the prompt and response in the case of R/O file overwrite, the command line can 
include the W parameter, as shown in this example: 


PIP A:=B:*.COM[M] 


The W parameter copies all nonsystem files to the A drive from the B drive and 
overwrites any R/O files in the process. If the operation involves several concatenated 
files, the W parameter need only be included with the last file in the list, as in this 
example: 


PIP A .DAT = B♦DAT tf :NEW♦DAT ,G:OLD.DATCW] 


Files with the system attribute can be included in PIP transfers if the R parameter is 
included; otherwise, system files are not recognized. For example, the command line: 

PIP ED. COM = B:ED.COMER] 


reads the ED ♦ COM file from the B drive, even if it has been marked as an R/O and pm 
system file. The system file attributes are copied, if present. 

Downward compatibility with previous versions of CP/M is only maintained if the 
file does not exceed one megabyte, no file attributes are set, and the file is created by 
user 0. If compatibility is required with nonstandard, for example, double-density 
versions of 1.4, it might be necessary to select 1.4 compatibility mode when construct¬ 
ing the internal disk parameter block. See Section 6 and refer to Section 6.10, which 
describes BIOS differences. 

Note: to copy files into another user area, PIP.COM must be located in that user area, mmi 
Use the following procedure to make a copy of PI P ♦ COM in another user area. 

USER 0 

DDT PIP.COM (note PIP size s) 

GO 

USER 3 

SAVES PIP.COM 

In this procedure, s is the integral number of memory pages, 256-byte segments, 
occupied by PIP. The number s can be determined when PIP.COM is loaded under 
DDT, by referring to the value under the NEXT display. If, for example, the next 


Log in user 0. 

Load PIP to memory. 
Return to CCP. 

Log in user 3. 
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available address is 1D00, then PI P ♦ COM requires 1C hexadecimal pages, or 1 times 16 
+ 12 = 28 pages, and the value of s is 28 in the subsequent save. Once PIP is copied in 
this manner, it can be copied to another disk belonging to the same user number 
through normal PIP transfers. 

1.6.5 ED Command 
Syntax: 


ED ufn 

The ED program is the CP/M system context editor that allows creation and altera¬ 
tion of ASCII files in the CP/M environment. Complete details of operation are given in 
Section 2. ED allows the operator to create and operate upon source files that are 
organized as a sequence of ASCII characters, separated by end-of-line characters (a 
carriage return/line-feed sequence). There is no practical restriction on line length (no 
single line can exceed the size of the working memory) that is defined by the number of 
characters typed between carriage returns. 

The ED program has a number of commands for character string searching, replace¬ 
ment, and insertion that are useful for creating and correcting programs or text files 
under CP/M. Although the CP/M has a limited memory work space area (approximate¬ 
ly 5000 characters in a 20K CP/M system), the file size that can be edited is not limited, 
since data are easily paged through this work area. 

If it does not exist, ED creates the specified source file and opens the file for access. If 
the source file does exist, the programmer appends data for editing (see the A com¬ 
mand). The appended data can then be displayed, altered, and written from the work 
area back to the disk (see the W command). Particular points in the program can be 
automatically paged and located by context, allowing easy access to particular portions 
of a large file (see the N command). 

If you type the following command line: 

ED X* ASM 

the ED program creates an intermediate work file with the name 
X ♦ $$$ 

to hold the edited data during the ED run. Upon completion of ED, the X ♦ ASM file 
(original file) is renamed toX ♦ BAK, and the edited work file is renamed to X ♦ ASM. 
Thus, the X ♦ BAK file contains the original unedited file, and the X ♦ ASM file contains 
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the newly edited file. The operator can always return to the previous version of a file by 
removing the most recent version and renaming the previous version. If the current 
X ♦ ASM file has been improperly edited, the following sequence of commands reclaim 
the back-up file. 

DIR X ♦ * Checks to see that BAK file is available. 

ERA X ♦ ASM Erases most recent version. 

REN X ♦ A S M = X ♦ B A K Renames the BAK file to ASM. 

You can abort the edit at any point (reboot, power failure, CTRL-C, or CTRL-Q 

command) without destroying the original file. In this case, the BAK file is not created 
and the original file is always intact. 

The ED program allows the user to edit the source on one disk and create the 
back-up file on another disk. This form of the ED command is 

ED ufn d: 

where ufn is the name of the file to edit on the currently logged disk and d is the name of 
an alternate drive. The ED program reads and processes the source file and writes the 
new file to drive d using the name ufn. After processing, the original file becomes the 
back-up file. If the operator is addressing disk A, the following command is valid. 

ED X. ASM b : 

This edits the file X ♦ ASM on drive A, creating the new file X ♦ $$$ on drive B. After a 
successful edit, A s X ♦ ASM is renamed to A : X ♦ BAK, and B : X ♦ $$$ is renamed to 
B : X ♦ ASM. For convenience, the currently logged disk becomes drive B at the end of the 
edit. Note that if a file named B : X ♦ ASM exists before the editing begins, the following 
message appears on the screen: 

FILE EXISTS 

This message is a precaution against accidentally destroying a source file. You should 
first erase the existing file and then restart the edit operation. 
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Similar to other transient commands, editing can take place on a drive different from 
the currently logged disk by preceding the source filename by a drive name. The 
following are examples of valid edit requests: 

ED A : X ♦ ASM Edits the file X ♦ ASM on drive A, with new file and back-up 

on drive A. 

ED B : X ♦ ASM A s Edits the file X ♦ ASM on drive B to the temporary file X ♦ $$$ 

on drive A. After editing, this command changes X ♦ ASM 
on drive B to X ♦ BAK and changes X ♦ $$$ on drive A to 
X. ASM 


1.6.6 SYSGEN Command 

Syntax: 


SYSGEN 

The SYSGEN transient command allows generation of an initialized disk containing 
the CP/M operating system. The SYSGEN program prompts the console for commands 
by interacting as shown. 

SYSGEN<cr> 


Initiates the SYSGEN program. 

SYSGEN VERSION x ♦ x 

SYSGEN sign-on message. 

SOURCE DRIVE NAME 
(OR RETURN TO SKIP) 

Respond with the drive name (one of the letters A, B, C, or D) of the 
disk containing a CP/M system, usually A. If a copy of CP/M already 
exists in memory due to a MOVCPM command, press only a carriage 
return. Typing a drive name d causes the response: 

SOURCE ON d THEN TYPE RETURN 

Place a disk containing the CP/M operating system on drive d (d is one 
of A, B, C, or D). Answer by pressing a carriage return when ready. 
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FUNCTION COMPLETE 

System is copied to memory. SYSGEN then prompts with the follow¬ 
ing: 

DESTINATION DRIVE NAME 
(OR RETURN TO REBOOT) 

If a disk is being initialized, place the new disk into a drive and answer 
with the drive name. Otherwise, press a carriage return and the system 
reboots from drive A. Typing drive name d causes SYSGEN to prompt 
with the following message: 

DESTINATION ON d 
THEN TYPE RETURN 

Place new disk into drive d; press return when ready. 

FUNCTION COMPLETE 

New disk is initialized in drive d. 

The DESTINATION prompt is repeated until a single carriage return is pressed at the 
console, so that more than one disk can be initialized. 

Upon completion of a successful system generation, the new disk contains the operat¬ 
ing system, and only the built-in commands are available. An IBM-compatible disk 
appears to CP/M as a disk with an empty directory; therefore, the operator must copy 
the appropriate COM files from an existing CP/M disk to the newly constructed disk 
using the PIP transient. 

You can copy all files from an existing disk by typing the following PIP command: 
PIP B : = A : * ♦ * [ u H 

This command copies all files from disk drive A to disk drive B and verifies that each file 
has been copied correctly. The name of each file is displayed at the console as the copy 
operation proceeds. 

Note that a SYSGEN Joes not destroy the files that already exist on a disk; it only 
constructs a new operating system. If a disk is being used only on drives B through P 
and will never be the source of a bootstrap operation on drive A, the SYSGEN need not 
take place. 
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1.6.7 SUBMIT Command 

Syntax: 


SUBMIT ufn parm#l . . . parm#n 

The SUBMIT command allows CP/M commands to be batched for automatic pro¬ 
cessing. The ufn given in the SUBMIT command must be the filename of a file that 
exists on the currently logged disk, with an assumed file type of SUB. The SUB file 
contains CP/M prototype commands with possible parameter substitution. The actual 
parameters parm#l . . . parm#n are substituted into the prototype commands, and, if 
no errors occur, the file of substituted commands are processed sequentially by CP/M. 

The prototype command file is created using the ED program, with interspersed $ 
parameters of the form: 

$1 $2 $3. . ,$n 

corresponding to the number of actual parameters that will be included when the file is 
submitted for execution. When the SUBMIT transient is executed, the actual para¬ 
meters parm#l . . . parm#n are paired with the formal parameters $1 ... $n in the 
prototype commands. If the numbers of formal and actual parameters do not corres¬ 
pond, the SUBMIT function is aborted with an error message at the console. The 
SUBMIT function creates a file of substituted commands with the name 

$$$♦SUB 

on the logged disk. When the system reboots, at the termination of the SUBMIT, this 
command file is read by the CCP as a source of input rather than the console. If the 
SUBMIT function is performed on any disk other than drive A, the commands are not 
processed until the disk is inserted into drive A and the system reboots. You can abort 
command processing at any time by pressing the rubout key when the command is read 
and echoed. In this case, the $$$ ♦ SUB file is removed and the subsequent commands 
come from the console. Command processing is also aborted if the CCP detects an 
error in any of the commands. Programs that execute under CP/M can abort processing 
of command files when error conditions occur by erasing any existing $ $ $ ♦ S U B file. 

To introduce dollar signs into a SUBMIT file, you can type a $$ which reduces to a 
single $ within the command file. An up arrow, T , precedes an alphabetic character s, 
which produces a single CTRL-X character within the file. 
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The last command in a SUB file can initiate another SUB file, allowing chained batch 
commands: 

Suppose the file ASMBL* SUB exists on disk and contains the prototype commands 

ASM $1 
DI R $ 1 ♦ * 

ERA * ♦ BAK 
PIP $2: =$1♦PRN 
ERA $1♦PRN 

then, you issue the following command: 

SUBMIT ASMBLX PRN 

The SUBMIT program reads the ASMBL«SUB file, substituting X: for all occurrences of 
$1 and PRN for all occurrences of $2. This results in a $$$*SUB file containing 
the commands: 

ASM X 
D I R X ♦ * 

ERA * ♦ BAK 
PIP PRN:= X ♦PRN 
ERA X,PRN 

which are executed in sequence by the CCP. 

The SUBMIT function can access a SUB file on an alternate drive by preceding the 
filename by a drive name. Submitted files are only acted upon when they appear on 
drive A. Thus, it is possible to create a submitted file on drive B that is executed at a 
later time when inserted in drive A. 
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An additional utility program called XSUB extends the power of the SUBMIT facility 
to include line input to programs as well as the CCP. The XSUB command is included 
as the first line of the SUBMIT file. When it is executed, XSUB self-relocates directly 
below the CCP. All subsequent SUBMIT command lines are processed by XSUB so that 
programs that read buffered console input, BDOS Function 10, receive their input 
directly from the SUBMIT file. For example, the file SAUER ♦ SUBcan contain the 
following SUBMIT lines: 


XSUB 

DDT 

I$1♦COM 
R 

GO 

SAME 1 $2 ♦ COM 

a subsequent SUBMIT command, such as 
A >SUBMIT SAUER PIP Y 

substitutes PIP for $1 and Y for $2 inthe command stream. The XSUB program loads, 
followed by DDT, which is sent to the command lines PIP* COM, R, and GO, thus 
returning to the CCP. The final command SAUE 1 Y*C0Mis processed by the CCP. 

The XSUB program remains in memory and prints the message 

(x s u b active) 

on each warm start operation to indicate its presence. Subsequent SUBMIT command 
streams do not require the X ♦ SUB * unless an intervening cold start occurs. Note that 
X*SUB must be loaded after the optional CP/M DESPOOL utility, if both are to run 
simultaneously. 

1.6.8 DUMP Command 

Syntax: 


DUMP ufn 

The DUMP program types the contents of the disk file (ufn) at the console in 
hexadecimal form. The file contents are listed sixteen bytes at a time, with the absolute 
byte address listed to the left of each line in hexadecimal. Long typeouts can be aborted 
by pressing the rubout key during printout. The source listing of the DUMP program is 
given in Section 5 as an example of a program written for the CP/M environment. 
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1.6.9 MOVCPM Command 

Syntax: 

MOVCPM 


MSHI 




The MOVCPM program allows you to reconfigure the CP/M system for any particu¬ 
lar memory size. Two optional parameters can be used to indicate the desired size of the 
new system and the disposition of the new system at program termination. If the first 
parameter is omitted or an * is given, the MOVCPM program reconfigures the system 
to its maximum size, based upon the kilobytes of contigous RAM in the host system 
(starting at 0000H). If the second parameter is omitted, the system is executed, but not 
permanently recorded; if * is given, the system is left in memory, ready for a SYSGEN ,mm i 

operation. The MOVCPM program relocates a memory image of CP/M and places this 
image in memory in preparation for a system generation operation. The following is a 
list of MOVCPM command forms: 


MOVCPM 


Relocates and executes CP/M for management of the 
current memory configuration (memory is examined 
for contiguous RAM, starting at 100H). On comple¬ 
tion of the relocation, the new system is executed but 
not permanently recorded on the disk. The system 
that is constructed contains a BIOS for the Intel MDS 
800. 


MOVCPMn 


MOVCPM * * 


MOVCPM n* 


Creates a relocated CP/M system for management of 
an n kilobyte system (n must be in the range of 20 to 
64), and executes the system as described. 

«■*!) 

Constructs a relocated memory image for the current 
memory configuration, but leaves the memory image 
in memory in preparation for a SYSGEN operation. ^ 

Constructs a relocated memory image for an n kilo¬ 
byte memory system, and leaves the memory image in 
preparation for a SYSGEN operation. 


PUP) 
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For example, the command, 

MOVCPM* * 

constructs a new version of the CP/M system and leaves it in memory, ready for a 
SYSGEN operation. The message 

READY FOR 'SYSGEN' OR 
' SAME 3d CPMx x♦COM ' 


appears at the console upon completion, where xx is the current memory size in 
kilobytes. You can then type the following sequence: 


SYSGEN 

SOURCE DR I ME NAME 
(OR RETURN TO SKIP) 


DESTINATION DR I ME NAME 
(OR RETURN TO REBOOT) 


DESTINATION ON B , 
THEN TYPE RETURN 


This starts the system generation. 

Respond with a carriage return to skip the 
CP/M read operation, because the system 
is already in memory as a result of the 
previous MOVCPM operation. 

Respond with B to write new system to 
the disk in drive B.SYSGEN prompts with 
the following message: 

Place the new disk on drive B and press 
the RETURN key when ready. 


If you respond with A rather than B above, the system is written to drive A rather 
than B. SYSGEN continues to print this prompt: 


DESTINATION DRIVE NAME (OR RETURN TO REBOOT) 

until you respond with a single carriage return, which stops the SYSGEN program with 
a system reboot. 
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You can then go through the reboot process with the old or new disk. Instead of 
performing the SYSGEN operation, you can type a command of the form: 

SAVE 34 CPMxx.COM 

at the completion of the MOVCPM function, where xx is the value indicated in the 
SYSGEN message. The CP/M memory image on the currently logged disk is in a form 
that can be patched. This is necessary when operating in a nonstandard environment 
where the BIOS must be altered for a particular peripheral device configuration, as 
described in Section 6. 

The following are valid MOVCPM commands: 

MOMCPM 48 Constructs a 48K version of CP/M and starts execution. 

M0MCPM48* Constructs a 48K version of CP/M in preparation for 

permanent recording; the response is 

READY FOR 'SYSGEN' DR 
'SAME 34 CPM48.COM' 

MOMCPM** Constructs a maximum memory version of CP/M and 

starts execution. 

The newly created system is serialized with the number attached to the original disk 
and is subject to the conditions of the Digital Research Software Licensing Agreement. 


1.7 BDOS Error Messages 

There are three error situations that the Basic Disk Operating System intercepts 
during file processing. When one of these conditions is detected, the BDOS prints the 
message: 

BDOS ERR ON d: error 

where d is the drive name and error is one of the three error messages: 

BAD SECTOR 
SELECT 
READ ONLY 
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The BAD SECTOR message indicates that the disk controller electronics has de¬ 
tected an error condition in reading or writing the disk. This condition is generally 
caused by a malfunctioning disk controller or an extremely worn disk. If you find that 
CP/M reports this error more than once a month, the state of the controller electronics 
and the condition of the media should be checked. 



You can also encounter this condition in reading files generated by a controller 
produced by a different manufacturer. Even though controllers claim to be IBM- 
compatible, one often finds small differences in recording formats. The MDS-800 
controller, for example, requires two bytes of ones following the data CRC byte, which 
is not required in the IBM format. As a result, disks generated by the Intel MDS can be 
read by almost all other IBM-compatible systems, while disk files generated on other 
manufacturers’ equipment produce the BAD SECTOR message when read by the 
MDS. To recover from this condition, press a CTRL-C to reboot (the safest course), or 
a return, which ignores the bad sector in the file operation. 

Note: pressing a return might destroy disk integrity if the operation is a directory 
write. Be sure you have adequate back-ups in this case. 


The SELECT error occurs when there is an attempt to address a drive beyond the 
range supported by the BIOS. In this case, the value of d in the error message gives the 
selected drive. The system reboots following any input from the console. 


pPRfil 




The READ ONLY message occurs when there is an attempt to write to a disk or file 
that has been designated as Read-Only in a STAT command or has been set to Read- 
Only by the BDOS. Reboot CP/M by using the warm start procedure, CTRL-C, or by 
performing a cold start whenever the disks are changed. If a changed disk is to be read 
but not written, BDOS allows the disk to be changed without the warm or cold start, 
but internally marks the drive as Read-Only. The status of the drive is subsequently 
changed to Read-Write if a warm or cold start occurs. On issuing this message, CP/M 
waits for input from the console. An automatic warm start takes place following any 
input. 
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1.8 Operation of CP/M on the MDS 

This section gives operating procedures for using CP/M on the Intel MDS micro¬ 
computer development system. Basic knowledge of the MDS hardware and software 
systems is assumed. 

CP/M is initiated in essentially the same manner as the Intel ISIS operating system. 
The disk drives are labeled 0 through 3 on the MDS, corresponding to CP/M drives A 
through D, respectively. The CP/M system disk is inserted into drive 0, and the BOOT 
and RESET switches are pressed in sequence. The interrupt 2 light should go on at this 
point. The space bar is then pressed on the system console, and the light should go out. 
If it does not, the user should check connections and baud rates. The BOOT switch is 
turned off, and the CP/M sign-on message should appear at the selected console device, 
followed by the A> system prompt. You can then issue the various resident and 
transient commands. 

The CP/M system can be restarted (warm start) at any time by pushing the INT 0 
switch on the front panel. The built-in Intel ROM monitor can be initiated by pushing 
the INT 7 switch, which generates an RST 7, except when operating under DDT, in 
which case the DDT program gets control instead. 

Diskettes can be removed from the drives at any time, and the system can be shut 
down during operation without affecting data integrity. Do not remove a disk and 
replace it with another without rebooting the system (cold or warm start) unless the 
inserted disk is Read-Only. 

As a result of hardware hang-ups or malfunctions, CP/M might print the following 
message: 

BDOS ERR ON d: BAD SECTOR 

where d is the drive that has a permanent error. This error can occur when drive doors 
are opened and closed randomly, followed by disk operations, or can be caused by a 
disk, drive, or controller failure. You can optionally elect to ignore the error by pressing 
a single return at the console. The error might produce a bad data record, requiring 
reinitialization of up to 128 bytes of data. You can reboot the CP/M system and try the 
operation again. 

Termination of a CP/M session requires no special action, except that it is necessary 
to remove the disks before turning the power off to avoid random transients that often 
make their way to the drive electronics. 
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1.8 Operation of CP/M on the MDS 


You should use IBM-compatible disks rather than disks that have previously been 
used with any ISIS version. In particular, the ISIS FORMAT operation produces non- 
I* 1 standard sector numbering throughout the disk. This nonstandard numbering seriously 
degrades the performance of CP/M, and causes CP/M to operate noticeably slower than 
the distribution version. If it becomes necessary to reformat a disk, which should not be 
p®* the case for standard disks, a program can be written under CP/M that causes the MDS 
800 controller to reformat with sequential sector numbering (1-26) on each track. 


Generally, IBM-compatible 8-inch disks do not need to be formatted. However, 
5 1/4-inch disks need to be formatted. 




End of Section 1 
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Section 2 

The CP/M Editor 




2.1 Introduction to ED 


ED is the context editor for CP/M, and is used to create and alter CP/M source files. 
To start ED, type a command of the following form: 


ED filename 






ED filename.typ 


Generally, ED reads segments of the source file given by filename or filename.typ into 
the central memory, where you edit the file and it is subsequently written back to disk 
after alterations. If the source file does not exist before editing, it is created by ED and 
initialized to empty. The overall operation of ED is shown in Figure 2-1. 


p™' 2.1.1 ED Operation 

EE) operates upon the source file, shown in Figure 2-1 by x.y, and passes all text 
through a memory buffer where the text can be viewed or altered. The number of lines 
that can be maintained in the memory buffer varies with the line length, but has a total 
capacity of about 5000 characters in a 20K CP/M system. 


jppii 


Edited text material is written into a temporary work file under your command. 
Upon termination of the edit, the memory buffer is written to the temporary file, 
followed by any remaining (unread) text in the source file. The name of the original file 
is changed from x.y to x.BAK so that the most recent edited source file can be reclaimed 
if necessary. See the CP/M commands ERASE and RENAME. The temporary file is 
then changed from x.$$$ to x.y, which becomes the resulting edited file. 
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The memory buffer is logically between the source file and working file, as shown in 
Figure 2-2. 
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SOURCE FILE 


MEMORY BUFFER 


TEMPORARY FILE 

FIRST LINE 

1 

FIRST LINE 

1 

FIRST LINE 

APPENDED 

2 

BUFFERED 

2 

PROCESSED 

LINES 


TEXT 


TEXT 












MP^ 


TP ► 


UNPROCESSED 

NEXT 

FREE 

NEXT 

FREE FILE 

SOURCE 

APPEND 

MEMORY 

WRITE 

SPACE 

LINES 


SPACE 




SP = SOURCE POINTER 
MP = MEMORY POINTER 
TP = TEMPORARY POINTER 


Figure 2-2. Memory Buffer Organization 


2.1.2 Text Transfer Functions 

Given that n is an integer value in the range 0 through 65535, several single-letter ED 
commands transfer lines of text from the source file through the memory buffer to the 
temporary (and eventually final) file. Single letter commands are shown in upper-case, 
but can be typed in either upper- or lower-case. 


Table 2-1. ED Text Transfer Commands 


Command 

Result 

nA 

Appends the next n unprocessed source lines from the source file at 
SP to the end of the memory buffer at MP. Increment SP and MP by 
n. If upper-case translation is set (see the U command) and the A 
command is typed in upper-case, all input lines will automatically be 
translated to upper-case. 

nW 

Writes the first n lines of the memory buffer to the temporary file free 
space. Shift the remaining lines n +1 through MP to the top of the 
memory buffer. Increment TP by n. 
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Table 2-1. (continued) 

Command 

Result 

E 

Ends the edit. Copy all buffered text to temporary file and copy all 
unprocessed source lines to temporary file. Rename files. 

H 

Moves to head of new file by performing automatic E command. The 
temporary file becomes the new source file, the memory buffer is 
emptied, and a new temporary file is created. The effect is equivalent 
to issuing an E command, followed by a reinvocation of ED, using 
x.y as the file to edit. 

0 

Returns to original file. The memory buffer is emptied, the tempor¬ 
ary file is deleted, and the SP is returned to position 1 of the source 
file. The effects of the previous editing commands are thus nullified. 

Q 

Quits edit with no file alterations, returns to CP/M. 


There are a number of special cases to consider. If the integer n is omitted in any ED 
command where an integer is allowed, then 1 is assumed. Thus, the commands A and 
W append one line and write one line, respectively. In addition, if a pound sign # is 
given in the place of n, then the integer 65535 is assumed (the largest value for n that is 
allowed). Because most source files can be contained entirely in the memory buffer, the 
command #A is often issued at the beginning of the edit to read the entire source file to 
memory. Similarly, the command #W writes the entire buffer to the temporary file. 

Two special forms of the A and W commands are provided as a convenience. The 
command OA fills the current memory buffer at least half full, while OW writes lines 
until the buffer is at least half empty. An error is issued if the memory buffer size is 
exceeded. You can then enter any command, such as W, that does not increase memory 
requirements. The remainder of any partial line read during the overflow will be 
brought into memory on the next successful append. 

2.1.3 Memory Buffer Organization 

The memory buffer can be considered a sequence of source lines brought in with the 
A command from a source file. The memory buffer has an imaginary character pointer 
(CP) that moves throughout the memory buffer under command of the operator. 
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The memory buffer appears logically as shown in Figure 2-3, where the dashes 
represent characters of the source line of indefinite length, terminated by carriage 
i return (<cr>) and line-feed (<lf>) characters, and CP represents the imaginary char¬ 
acter pointer. Note that the CP is always located ahead of the first character of the first 
line, behind the last character of the last line, or between two characters. The current 
, line CL is the source line that contains the CP. 


MEMORY BUFFER 



Figure 2-3. Logical Organization of Memory Buffer 


2.1.4 Line Numbers and ED Start-up 

ED produces absolute line number prefixes that are used to reference a line or range 
of lines. The absolute line number is displayed at the beginning of each line when ED is 
in insert mode (see the I command in Section 2.1.5). Each line number takes the form 


nnnnn: 


where nnnnn is an absolute line number in the range of 1 to 65535. If the memory 
buffer is empty or if the current line is at the end of the memory buffer, nnnnn appears 
as 5 blanks. 
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You can reference an absolute line number by preceding any command by a number 
followed by a colon, in the same format as the line number display. In this case, the ED 
program moves the current line reference to the absolute line number, if the line exists 
in the current memory buffer. The line denoted by the absolute line number must be in 
the memory buffer (see the A command). Thus, the command 

345 s T 

is interpreted as move to absolute 345, and type the line. Absolute line numbers are 
produced only during the editing process and are not recorded with the file. In particu¬ 
lar, the line numbers will change following a deleted or expanded section of text. 

You can also reference an absolute line number as a backward or forward distance 
from the current line by preceding the absolute number by a colon. Thus, the command 

: 4 0 0 T 

is interpreted as type from the current line number through the line whose absolute 
number is 400. Combining the two line reference forms, the command 

345::4 0 0 T 

is interpreted as move to absolute line 345, then type through absolute line 400. 
Absolute line references of this sort can precede any of the standard ED commands. 

Line numbering is controlled by the V (Verify Line Numbers) command. Line 
numbering can be turned off by typing the - V command. 

If the file to edit does not exist, ED displays the following message: 

NEW FILE 

To move text into the memory buffer, you must enter an i command before typing 
input lines and terminate each line with a carriage return. A single CTRL-Z character 
returns ED to command mode. 
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2.1.5 Memory Buffer Operation 

When ED begins, the memory buffer is empty. You can either append lines from the 
source file with the A command, or enter the lines directly from the console with the 
insert command. The insert command takes the following form: 

I 


pus 


ED then accepts any number of input lines. You must terminate each line with a <cr> 
(the <lf> is supplied automatically). A single CTRL-Z, denoted by an up arrow (T)Z, 
returns ED to command mode. The CP is positioned after the last character entered. 
The following sequence: 

I<cr> 


NON IS THE<cr> 
mm TINE F0R<cr> 

ALL GOOD MEN<cr> 
TZ 


leaves the memory buffer as 


NOW IS THE<cr><lf> 

H* TIME FOR<cr><lf> 

ALL GOOD MEN<cr><lf> 


Generally, ED accepts command letters in upper- or lower-case. If the command is 
- upper-case, all input values associated with the command are translated to upper-case. 
If the I command is typed, all input lines are automatically translated internally to 
upper-case. The lower-case form of the i command is most often used to allow both 
. upper- and lower-case letters to be entered. 




Various commands can be issued that control the CP or display source text in the 
vicinity of the CP. The commands shown below with a preceding n indicate that an 
optional unsigned value can be specified. When preceded by ±, the command can be 
unsigned, or have an optional preceding plus or minus sign. As before, the pound sign 
# is replaced by 65535. If an integer n is optional, but not supplied, then n = l is 
assumed. Finally, if a plus sign is optional, but none is specified, then + is assumed. 
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Table 2-2. Editing Commands 


Command 

Action 

±B 

Move CP to beginning of memory buffer if + and to bottom if —. 

± nC 

Move CP by ±n characters (moving ahead if + ), counting the 
<cr><lf> as two characters. 

± nD 

Delete n characters ahead of CP if plus and behind CP if minus. 

± nK 

Kill (remove) ±n lines of source text using CP as the current refer¬ 
ence. If CP is not at the beginning of the current line when K is 
issued, the characters before CP remain if + is specified, while the 
characters after CP remain if - is given in the command. 

±nL 

If n = 0, move CP to the beginning of the current line, if it is not 
already there. If n 4 0, first move the CP to the beginning of the 
current line and then move it to the beginning of the line that is n 
lines down (if +) or up (if - ). The CP will stop at the top or bottom 
of the memory buffer if too large a value of n is specified. 

± nT 

If n = 0, type the contents of the current line up to CP. If n = 1, type 
the contents of the current line from CP to the end of the line. If n> 1, 
type the current line along with n — 1 lines that follow, if + is 
specified. Similarly, if n>l and - is given, type the previous n lines 
up to the CP. Any key can be depressed to abort long type-outs. 

± n 

Equivalent to ±nLT, which moves up or down and types a single 
line. 




(** 1 ^ 




2.1.6 Command Strings 

Any number of commands can be typed contiguously (up to the capacity of the 
console buffer) and are executed only after you press the <cr>. Table 2-3 summarizes 
the CP/M console line-editing commands used to control the input command line. 
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Table 2-3. Line-editing Controls 


Command 

Result 

CTRL-C 

Reboots the CP/M system when typed at the start of a line. 

CTRL-E 

Physical end of line: carriage is returned, but line is not sent 
until the carriage return key is depressed. 

CTRL-H 

Backspaces one character position. 

CTRL-J 

Terminates current input (line-feed). 

CTRL-M 

Terminates current input (carriage return). 

CTRL-R 

Retypes current command line: types a clean line character 
deletion with rubouts. 

CTRL-U 

Deletes the entire line typed at the console. 

CTRL-X 

Same as CTRL-U. 

CTRL-Z 

Ends input from the console (used in PIP and ED). 

rub/del 

Deletes and echos the last character typed at the console. 
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Suppose the memory buffer contains the characters shown in the previous section, 
with the CP following the last character of the buffer. In the following example, the 
command strings on the left produce the results shown to the right. Use lower-case 
command letters to avoid automatic translation of strings to upper-case. 


Command String 
B2T<cr> 


5C0T<cr> 


2L-T<cr> 


-L#K<cr> 


I <cr> 

TIME TO<cr> 
I NSERT<cr> 
TZ 


Effect 

Move to beginning of the buffer and type two lines: 

NOW IS THE 
TIME FOR 


The result in the memory buffer is 

"NOW IS THE<cr><lf> 

TIME FOR<cr><lf> 

ALL GOOD MEN<cr><lf> 

Move CP five characters and type the beginning of the line 
NOW I. The result in the memory buffer is 

NOW IS THE<cr><lf> 


Move two lines down and type the previous line TIME 
FOR. The result in the memory buffer is 

NOW IS THE<cr><lf> 

TIME FOR<cr><lf> 

^ALL GOOD MEN<crXlf> 

Move up one line, delete 65535 lines that follow. The 
result in the memory buffer is 

NOW IS THE<crXlf> 


Insert two lines of text with automatic translation to up¬ 
per-case. The result in the memory buffer is 


2-10 


NOW IS THE<cr><lf> 
TIME TO<crXlf> 
INSERT<cr><lf> 
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Command String 


Effect 


-2L#T<cr> 


<cr> 


Move up two lines and type 65535 lines ahead of CP 
NOW IS THE. The result in the memory buffer is 

NOW IS THE<cr><lf> 

TIME TO<cr><lf> 

INSERT<cr><lf> 

Move down one line and type one line INSERT. The result 
in the memory buffer is 

NOW IS THE<crXlf> 

TIME TO<crXlf> 

INSERT<crXlf> 


2.1.7 Text Search and Alteration 

ED has a command that locates strings within the memory buffer. The command 
takes the form 

nF s <cr> 

or 

nF s TZ 

where s represents the string to match, followed by either a <cr> or CTRL-Z, denoted 
by TZ. ED starts at the current position of CP and attempts to match the string. The 
match is attempted n times and, if successful, the CP is moved directly after the string. If 
the n matches are not successful, the CP is not moved from its initial position. Search 
strings can include CTRL-L, which is replaced by the pair of symbols <cr><lf>. 
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The following comma 

nds illustrate the use of the F command: 


Command String 

Effect 


B#T<cr> 

Move to the beginning and type the entire buffer. The 
result in the memory buffer is 



NOW IS THE <cr>< lf> 



TIME FOR<cr><lf> 

ALL GOOD MEN<cr><lf> 


FS T<cr> 

Find the end of the string S T. The result in the memory 
buffer is 



NOW IS T HE<crXlf > 

MR, 

FIsTZOTT 

Find the next I and type to the CP; then type the remainder 
of the current line ME FOR. The result in the memory 
buffer is 



NOW IS THE<crXl f> 



TIME FOR<crXlf> 



ALL GOOD MEN<crXlf> 


An abbreviated form 

of the insert command is also allowed, which is often used in 


conjunction with the F command to make simple textual changes. The form is 

r«Siij 

IstZ 



or 



Is<cr> 



where s is the string to 

insert. If the insertion string is terminated by a CTRL-Z, the 


string is inserted directly following the CP, and the CP is positioned directly after the 
string. The action is the same if the command is followed by a <cr> except that a 
<cr><lf> is automatically inserted into the text following the string. The following 
command sequences are examples of the F and I commands: 




(iDl nir.ITA! RFQFARrH 1 ' 1 
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Command String 
BITHIS IStZ <cr> 


FTIMETZ-4DIPLACETZ <cr> 


3F0IZ-3D5D1 
CHANGEStZ <cr> 


-8C I SOURCE <cr> 


Effect 

Insert THIS IS at the beginning of the text. The 
result in the memory buffer is 

THIS IS “ NOW THE<cr><lf> 

TIME FOR<cr><lf> 

ALL GOOD MEN<cr><lf> 

Find TIME and delete it; then insert PLACE. 
The result in the memory buffer is 

THIS IS NOW THE<cr><lf> 

PLACE * FOR<crXlf> 

ALL GOOD MEN<cr><lf> 

Find third occurrence of O (that is, the second 
O in GOOD), delete previous 3 characters and 
the subsequent 5 characters; then insert 
CHANGES. The result in the memory buffer is 

THIS IS NOW THE<cr><lf> 

PLACE FOR<cr><lf> 

ALL CHANGES <crXlf> 

Move back 8 characters and insert the line 
SOURCE<cr><lf>. The result in the memory 
buffer is 

THIS IS NOW THE<cr><lf> 

PLACE FOR<crXlf> 

ALL SOURCE<cr><lf> 
CHANGES<crXlf> 
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ED also provides a single command that combines the F and I commands to perform 
simple string substitutions. The command takes the following form: 

eiif#} 

nS s^Zs 2 <cr> 

qj* 


nS S!tZs 2 TZ 

and has exactly the same effect as applying the following command string a total of n 
times: 

F sitZ-kDIs 2 <cr> 






or 


F Sl tZ-kDIs 2 TZ 


where k is the length of the string. ED searches the memory buffer starting at the **1 
current position of CP and successively substitutes the second string for the first string 
until the end of buffer, or until the substitution has been performed n times. 

As a convenience, a command similar to F is provided by ED that automatically 
appends and writes lines as the search proceeds. The form is 


n N s <cr> 




OF 

nNstZ 

which searches the entire source file for the nth occurrence of the strings (you should 
recall that F fails if the string cannot be found in the current buffer). The operation of 
the N command is precisely the same as F except in the case that the string cannot be 
found within the current memory buffer. In this case, the entire memory content is 
written (that is, an automatic #W is issued). Input lines are then read until the buffer is 
at least half full, or the entire source file is exhausted. The search continues in this 
manner until the string has been found n times, or until the source file has been 
completely transferred to the temporary file. 
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A final line editing function, called the juxtaposition command, takes the form 
n J SitZs 2 tZs3 <cr> 
or 

n JsiTZs 2 TZs 3 tZ 

with the following action applied n times to the memory buffer: search from the current 
CP for the next occurrence of the string sj. If found, insert the string S 2 , and move CP to 
follow s 2 . Then delete all characters following CP up to, but not including, the string s 3 , 
leaving CP directly after s 2 . If s 3 cannot be found, then no deletion is made. If the 
current line is 

NON IS THE TIME <cr><lf> 
the command 
JNtZNHATtZTl <cr> 
results in 

NON NHAT<cr><lf> 

You should recall that T1 (CTRL-L) represents the pair <cr><lf> in search and substi¬ 
tute strings. 

The number of characters ED allows in the F, S, N, and J commands is limited to 100 
symbols. 

2.1.8 Source Libraries 

ED also allows the inclusion of source libraries during the editing process with the R 
command. The form of this command is 

R filename TZ 

or 

R filename <cr> 
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where filename is the primary filename of a source file on the disk with an assumed 
filetype of LIB. ED reads the specified file, and places the characters into the memory 
buffer after CP, in a manner similar to the I command. Thus, if the command 

RMACRO <cr> 

is issued by the operator, ED reads from the file MACRO.LIB until the end-of-file and 
automatically inserts the characters into the memory buffer. 

ED also includes a block move facility implemented through the X (Transfer) com¬ 
mand. The form 

nX 

transfers the next n lines from the current line to a temporary file called 
)<$$$$$$ ♦ L IB 

which is active only during the editing process. You can reposition the current line 
reference to any portion of the source file and transfer lines to the temporary file. The 
transferred lines accumulate one after another in this file and can be retrieved by simply 
typing 

R 

which is the trivial case of the library read command. In this case, the entire transferred 
set of lines is read into the memory buffer. Note that the X command does not remove 
the transferred lines from the memory buffer, although a K command can be used 
directly after the X, and the R command does not empty the transferred LIB file. That 
is, given that a set of lines has been transferred with the X command, they can be reread 
any number of times back into the source file. The command 


is provided to empty the transferred line file. 

Note that upon normal completion of the ED program through Q or E, the tempor¬ 
ary LIB file is removed. If ED is aborted with a CTRL-C, the LIB file will exist if lines 
have been transferred, but will generally be empty (a subsequent ED invocation will 
erase the temporary file). 
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2.1.9 Repetitive Command Execution 

The macro command M allows you to group ED commands together for repeated 
evaluation. The M command takes the following form: 

nMCS <cr> 

or 

n M CS TZ 

where CS represents a string of ED commands, not including another M command. ED 
executes the command string n times if n>l. If n = 0 or 1, the command string is 
executed repetitively until an error condition is encountered (for example, the end of 
the memory buffer is reached with an F command). 

As an example, the following macro changes all occurrences of GAMMA to DELTA 
within the current buffer, and types each line that is changed: 

MFGAMMATZ-5DIDELTATZ0TT <cr> 

or equivalently 

MSGAMMAtZDELTAtZOTT <cr> 
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2.2 ED Error Conditions 

On error conditions, ED prints the message BREAK X AT C where X is one of the 
error indicators shown in Table 2-4. 


Table 2-4. Error Message Symbols 


Symbol 

Meaning 

p 

Unrecognized command. 

> 

Memory buffer full (use one of the commands D, K, N, S, or W to 
remove characters); F, N, or S strings too long. 

# 

Cannot apply command the number of times specified (for example, 
in F command). 

o 

Cannot open LIB file in R command. 










If there is a disk error, CP/M displays the following message: 

BDOS ERR on ds BAD SECTOR 

You can choose to ignore the error by pressing RETURN at the console (in this case, **1 
the memory buffer data should be examined to see if they were incorrectly read), or you 
can reset the system with a CTRL-C and reclaim the back-up file if it exists. The file can 
be reclaimed by first typing the contents of the BAK file to ensure that it contains the 
proper information. For example, type the following: 


TYPE x♦BAK 

where x is the file being edited. Then remove the primary file 
ERA x ♦ y 

and rename the BAK file 
REN x ♦ y = x ♦ BAK 

The file can then be reedited, starting with the previous version. 
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ED also takes file attributes into account. If you attempt to edit a Read-Only file, the 
message 

** FILE IS READ/ONLY ** 

appears at the console. The file can be loaded and examined, but cannot be altered. You 
must end the edit session and use STAT to change the file attribute to R/W. If the edited 
file has the system attribute set, the following message: 

'SYSTEM' FILE NOT ACCESSIBLE 

is displayed and the edit session is aborted. Again, the STAT program can be used to 
change the system attribute, if desired. 

2.3 Control Characters and Commands 

Table 2-5 summarizes the control characters and commands available in ED. 


Table 2-5. ED Control Characters 


Control Character 

Function 

CTRL-C 

System reboot 

CTRL-E 

Physical <cr><lf> (not actually entered in command) 

CTRL-H 

Backspace 

CTRL-J 

Logical tab (cols 1, 9,16,. . .) 

CTRL-L 

Logical <cr><lf> in search and substitute strings 

CTRL-R 

Repeat line 

CTRL-U 

Line delete 

CTRL-X 

Line delete 

CTRL-Z 

String terminator 

rub/del 

Character delete 
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Table 2-6 summarizes the commands used in ED. 


Table 2-6. ED Commands 


Command 

Function 

nA 

Append lines 

± B 

Begin or bottom of buffer 

±nC 

Move character positions 

±nD 

Delete characters 

E 

End edit and close files (normal end) 

nF 

Find string 

H 

End edit, close and reopen files 

I 

Insert characters, use i if both upper- and lower-case 
characters are to be entered. 

nj 

Place strings in juxtaposition 

±nK 

Kill lines 

± nL 

Move down/up lines 

nM 

Macro definition 

nN 

Find next occurrence with autoscan 

O 

Return to original file 

±nP 

Move and print pages 

Q 

Quit with no file changes 

R 

Read library file 


MM!^ 






flBtl ^ 




iRMl^ 
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Table 2-6. (continued) 


Command 

Function 

nS 

Substitute strings 

±nT 

Type lines 

±u 

Translate lower- to upper-case if U, no translation if 
-U 

± V 

Verify line numbers, or show remaining free character 
space 

ov 

A special case of the V command, OV, prints the mem¬ 
ory buffer statistics in the form 


free/total 


where free is the number of free bytes in the memory 
buffer (in decimal) and total is the size of the memory 
buffer 

nW 

Write lines 

nZ 

Wait (sleep) for approximately n seconds 

± n 

Move and type (± nLT). 


Because of common typographical errors, ED requires several potentially disastrous 
commands to be typed as single letters, rather than in composite commands. The 
following commands: 

■ E(end) 

■ H(head) 

■ O(original) 

■ Q(quit) 

must be typed as single letter commands. 
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The commands I, J, M, N, R, and S should be typed as i, j, m, n, r, and s if both 
upper- and lower-case characters are used in the operation, otherwise all characters are 
converted to upper-case. When a command is entered in upper-case, ED automatically 
converts the associated string to upper-case, and vice versa. 


End of Section 2 
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Section 3 
CP/M Assembler 


3.1 Introduction 

The CP/M assembler reads assembly-language source files from the disk and pro¬ 
duces 8080 machine language in Intel hex format. To start the CP/M assembler, type a 
command in one of the following forms: 

ASM filename 
ASM filename.parms 

In both cases, the assembler assumes there is a file on the disk with the name: 
f i 1 ename♦ASM 

which contains an 8080 assembly-language source file. The first and second forms 
shown above differ only in that the second form allows parameters to be passed to the 
assembler to control source file access and hex and print file destinations. 

In either case, the CP/M assembler loads and prints the message: 

CP/M ASSEMBLER VER n.n 

where n.n is the current version number. In the case of the first command, the assembler 
reads the source file with assumed filetype ASM and creates two output files 


f i 1 e n a m e ♦ H E X 
f i 1 e n a m e ♦ P R N 



The HEX file contains the machine code corresponding to the original program in 
Intel hex format, and the PRN file contains an annotated listing showing generated 
machine code, error flags, and source lines. If errors occur during translation, they are 
listed in the PRN file and at the console. 
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The form ASM filename parms is used to redirect input and output files from their 
defaults. In this case, the parms portion of the command is a three-letter group that 
specifies the origin of the source file, the destination of the hex file, and the destination 
of the print file. The form is 

filename. plp2p3 


where pi, p2, and p3 are single letters. PI can be 


A,B,. .. ,P 


MMNij 


which designates the disk name that contains the source file. P2 can be 
A,B,...,P 

which designates the disk name that will receive the hex file; or, P2 can be 
Z 

which skips the generation of the hex file. 


Urn# 




P3 can be 
A,B,. . .,P 

which designates the disk name that will receive the print file. P3 can also be specified as 






X 

which places the listing at the console; or 
Z 


ffsIW 1 \ 


which skips generation of the print file. Thus, the command 


ASM X. AAA 


indicates that the source, X ♦ HEX, and print, X ♦ PRfiles are also to be created on disk 
A. This form of the cornu ;nd is implied if the assembler is run from disk A. Given that 
you are currently addressing disk A, the above command is the same as 


ASM X 
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The command 


ASM X ♦ A BX 

indicates that the source file is to be taken from disk A, the hex file is to be placed on 
disk B, and the listing file is to be sent to the console. The command 


ASM X.BZZ 


takes the source file from disk B and skips the generation of the hex and print files. This 
command is useful for fast execution of the assembler to check program syntax. 

The source program format is compatible with the Intel 8080 assembler. Macros are 
not implemented in ASM; see the optional MAC macro assembler. There are certain 
extensions in the CP/M assembler that make it somewhat easier to use. These exten¬ 
sions are described below. 


3.2 Program Format 

An assembly-language program acceptable as input to the assembler consists of a 
sequence of statements of the form 

line# label operation operand ;comment 

where any or all of the fields may be present in a particular instance. Each assembly- 
language statement is terminated with a carriage return and line-feed (the line-feed is 
inserted automatically by the ED program), or with the character !, which is treated as 
an end-of-line by the assembler. Thus, multiple assembly-language statements can be 
written on the same physical line if separated by exclamation point symbols. 

The line# is an optional decimal integer value representing the source program line 
number, and ASM ignores this field if present. 

The label field takes either of the following forms: 

identifier 

identifier: 

The label field is optional, except where noted in particular statement types. The 
identifier is a sequence of alphanumeric characters where the first character is alpha¬ 
betic. Identifiers can be freely used by the programmer to label elements such as 
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program steps and assembler directives, but cannot exceed 16 characters in length. All 
characters are significant in an identifier,‘except for the embedded dollar symbol $, 
which, can be used to improve readability of the name. Further, all lower-case alpha¬ 
bets are treated as upper-case^The following are all valid instances of labels: 


X 

x y 

1 o n a $ n a m e 

x : 

y x 1 : 

1 o n a e r $n ame d $ d a t a : 

X1Y2 

X1 x2 

x234*5678$9012$3fl56s 


The operation field contains either an assembler directive or pseudo operation, or an 
8080 machine operation code. The pseudo operations and machine operation codes are 
described in Section 3.3. 

Generally, the operand field of the statement contains an expression formed out of 
constants and labels, along with arithmetic and logical operations on these elements. 
Again, the complete details of properly formed expressions are given in Section 3.3. 

The comment field contains arbitrary characters following the semicolon symbol 
until the next real or logical end-of-line. These characters are read, listed, and otherwise 
ignored by the assembler. The CP/M assembler also treats statements that begin with 
an * in column one as comment statements that are listed and ignored in the assembly 
process. 

The assembly-language program is formulated as a sequence of statements of the 
above form, terminated by an optional END statement. All statements following the 
END are ignored by the assembler. 


3.3 Forming the Operand 

To describe the operation codes and pseudo operations completely, it is necessary 
first to present the form of the operand field, since it is used in nearly all statements. 
Expressions in the operand field consist of simple operands, labels, constants, and 
reserved words, combined in properly formed subexpressions by arithmetic and logical 
operators. The expression computation is carried out by the assembler as the assembly 
proceeds. Each expression must produce a 16-bit value during the assembly. Further, 
the number of significant digits in the result must not exceed the intended use. If an 
expression is to be used in a byte move immediate instruction, the most significant 8 
bits of the expression must be zero. The restriction on the expression significance is 
given with the individual instructions. 
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3.3.1 Labels 

A label is an identifier that occurs on a particular statement. In general, the label is 
given a value determined by the type of statement that it precedes. If the label occurs on 
a statement that generates machine code or reserves memory space (for example, a 
MOV instruction or a DS pseudo operation), the label is given the value of the program 
address that it labels. If the label precedes an EQU or SET, the label is given the value 
that results from evaluating the operand field. Except for the SET statement, an iden¬ 
tifier can label only one statement. 

When a label appears in the operand field, its value is substituted by the assembler. 
This value can then be combined with other operands and operators to form the 
operand field for a particular instruction. 

3.3.2 Numeric Constants 

A numeric constant is a 16-bit value in one of several bases. The base, called the 
radix of the constant, is denoted by a trailing radix indicator. The following are radix 
indicators: 

■ B is a binary constant (base 2). 

■ O is a octal constant (base 8). 

■ Q is a octal constant (base 8). 

■ D is a decimal constant (base 10). 

■ H is a hexadecimal constant (base 16). 

Q is an alternate radix indicator for octal numbers because the letter O is easily 
confused with the digit 0. Any numeric constant that does not terminate with a radix 
indicator is a decimal constant. 

A constant is composed as a sequence of digits, followed by an optional radix 
indicator, where the digits are in the appropriate range for the radix. Binary constants 
must be composed of 0 and 1 digits, octal constants can contain digits in the range 0—7, 
while decimal constants contain decimal digits. Hexadecimal constants contain decimal 
digits as well as hexadecimal digits A(10D), B(11D), C(12D), D(13D), E(14D), and 
F(15D). Note that the leading digit of a hexadecimal constant must be a decimal digit 
to avoid confusing a hexadecimal constant with an identifier. A leading 0 will always 
suffice. A constant composed in this manner must evaluate to a binary number that can 
be contained within a 16-bit counter, otherwise it is truncated on the right by the 
assembler. 
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Similar to identifiers, embedded $ signs are allowed within constants to improve their 
readability. Finally, the radix indicator is translated to upper-case if a lower-case letter 
is encountered. The following are all valid instances of numeric constants: 

1234 1234D UOOB 1 1 11$0000$1111$0000B 

1234H OFFEH 33770 33$77$22Q 

3377o Of e3h 1234d Offffh 

3.3.3 Reserved Words 

There are several reserved character sequences that have predefined meanings in the 
operand field of a statement. The names of 8080 registers are given below. When they 
are encountered, they produce the values shown to the right. 


Table 3-1. Reserved Characters 


Character 

Value 

A 

7 

B 

0 

C 

1 

D 

2 

E 

3 

H 

4 

L 

5 

M 

6 

SP 

6 

PSW 

6 


Again, lower-case names have the same values as their upper-case equivalents. 
Machine instructions can also be used in the operand field; they evaluate to their 
internal codes. In the case of instructions that require operands, where the specific 
operand becomes a part of the binary bit pattern of the instruction, for example, MOV 
A,B, the value of the instruction, in this case MOV, is the bit pattern of the instruction 
with zeros in the optional fields, for example, MOV produces 40H. 

When the symbol $ occurs in the operand field, not embedded within identifiers and 
numeric constants, its value becomes the address of the next instruction to generate, 
not including the instruction contained within the current logical line. 
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3.3.4 String Constants 

String constants represent sequences of ASCII characters and are represented by 
enclosing the characters within apostrophe symbols. All strings must be fully contained 
within the current physical line (thus allowing exclamation point symbols within 
strings) and must not exceed 64 characters in length. The apostrophe character itself 
can be included within a string by representing it as a double apostrophe (the two 
keystrokes 4 ’), which becomes a single apostrophe when read by the assembler. In most 
cases, the string length is restricted to either one or two characters (the DB pseudo 
operation is an exception), in which case the string becomes an 8- or 16-bit value, 
respectively. Two-character strings become a 16-bit constant, with the second charac¬ 
ter as the low-order byte, and the first character as the high-order byte. 

The value of a character is its corresponding ASCII code. There is no case translation 
within strings; both upper- and lower-case characters can be represented. You should 
note that only graphic printing ASCII characters are allowed within strings. 


Valid strings: 

'A' 7 AB 7 7 a b 7 'c' 

// /_./// //// //// 
a 

'Walla Walla Wash ♦ 7 
7 She said"Hello" to me* 
7 I said "Hello" to her* 7 


How assembler reads strings: 

A AB at> c 
a 7 7 7 

WallaWallaWash* 

She said "Hello" to me 
I said "Hello" to her* 


3.3.5 Arithmetic and Logical Operators 

The operands described in Section 3.3 can be combined in normal algebraic notation 
using any combination of properly formed operands, operators, and parenthesized 
expressions. The operators recognized in the operand field are described in Table 3-2. 


Table 3-2. Arithmetic and Logical Operators 


Operators 

Meaning 

a + b 

unsigned arithmetic sum of a and b 

a - b 

unsigned arithmetic difference between a and b 

+ b 

unary plus (produces b) 

- b 

unary minus (identical to 0 — b) 
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Table 3-2. (continued) 


Operators 

Meaning 

a*b 

unsigned magnitude multiplication of a and b 

a / b 

unsigned magnitude division of a by b 

a MOD b 

remainder after a / b. 

NOTb 

logical inverse of b (all Os become Is, Is become Os), 
where b is considered a 16-bit value 

a AND b 

bit-by-bit logical and of a and b 

aORb 

bit-by-bit logical or of a and b 

aXORb 

bit-by-bit logical exclusive or of a and b 

aSHLb 

the value that results from shifting a to the left by an 
amount b, with zero fill 

aSHRb 

the value that results from shifting a to the right by an 
amount b, with zero fill 











In each case, a and b represent simple operands (labels, numeric constants, reserved 
words, and one- or two-character strings) or fully enclosed parenthesized subexpres¬ 
sions, like those shown in the following examples: 


10 + 20 10h + 370 Ll/3 (L2+4) SHR3 

('a'and5fh>+'0'( ' B ' +B)OR( PSW+M ) 


IM^ 


(l+(2 + c))sh r(A-(B+l ) ) 

Note that all computations are performed at assembly time as 16-bit unsigned opera¬ 
tions. Thus, — 1 is computed as 0 — 1, which results in the value Offffh (that is, all Is). 
The resulting expression must fit the operation code in which it is used. For example, if 
the expression is used in an ADI (add immediate) instruction, the high-order 8 bits of 
the expression must be zero. As a result, the operation ADI -1 produces an error 
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message ( — 1 becomes Offffh, which cannot be represented as an 8-bit value), while 
ADI(- 1) AND OFFH is accepted by the assembler because the AND operation zeros 
the high-order bits of the expression. 

3.3.6 Precedence of Operators 

As a convenience to the programmer, ASM assumes that operators have a relative 
precedence of application that allows the programmer to write expressions without 
nested levels of parentheses. The resulting expression has assumed parentheses that are 
defined by the relative precedence. The order of application of operators in unparenthe¬ 
sized expressions is listed below. Operators listed first have highest precedence (they are 
applied first in an unparenthesized expression), while operators listed last have lowest 
precedence. Operators listed on the same line have equal precedence, and are applied 
from left to right as they are encountered in an expression. 

*/MOD SHL SHR 

- + 

NOT 
AND 
□ R XOR 

Thus, the expressions shown to the left below are interpreted by the assembler as the 
fully parenthesized expressions shown to the right. 

a*b + c (a*b) + c 

a + b*c a + (b*c) 

a MOD b*c SHL d ((a MOD b)*c) SHLd 

a OR b AND NOT c + d SHL e a OR (b AND (NOT (c+ (d SHL e)))) 

Balanced, parenthesized subexpressions can always be used to override the assumed 
parentheses; thus, the last expression above could be rewritten to force application of 
operators in a different order, as shown: 

(a OR b) AND (NOT c) + d SHL e 
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This results in these assumed parentheses: 

( a OR b ) AND ( ( NOT c ) + ( d SHL e ) ) 

An unparenthesized expression is well-formed only if the expression that results from 
inserting the assumed parentheses is well-formed. 


3.4 Assembler Directives 

Assembler directives are used to set labels to specific values during the assembly, 
perform conditional assembly, define storage areas, and specify starting addresses in 
the program. Each assembler directive is denoted by a pseudo operation that appears 
in the operation field of the line. The acceptable pseudo operations are shown in 
Table 3-3. 


Table 3-3. Assembler Directives 


Directive 

Meaning 

ORG 

set the program or data origin 

END 

end program, optional start address 

EQU 

numeric equate 

SET 

numeric set 

IF 

begin conditional assembly 

ENDIF 

end of conditional assembly 

DB 

define data bytes 

DW 

define data words 

DS 

define data storage area 
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3.4 Assembler Directives 


JUS* 


3.4.1 The ORG Directive 

The ORG statement takes the form: 

label ORG expression 

where label is an optional program identifier and expression is a 16-bit expression, 
consisting of operands that are defined before the ORG statement. The assembler 
begins machine code generation at the location specified in the expression. There can be 
any number of ORG statements within a particular program, and there are no checks 
to ensure that the programmer is not defining overlapping memory areas. Note that 
most programs written for the CP/M system begin with an ORG statement of the form: 

ORG 100H 

which causes machine code generation to begin at the base of the CP/M transient 
program area. If a label is specified in the ORG statement, the label is given the value of 
the expression. This label can then be used in the operand field of other statements to 
represent this expression. 

3.4.2 The END Directive 

The END statement is optional in an assembly-language program, but if it is present 
it must be the last statement. All subsequent statements are ignored in the assembly. 
The END statement takes the following two forms: 

label END 

label END expression 

where the label is again optional. If the first form is used, the assembly process stops, 
and the default starting address of the program is taken as 0000. Otherwise, the 
expression is evaluated, and becomes the program starting address. This starting 
address is included in the last record of the Intel-formatted machine code hex file that 
results from the assembly. Thus, most CP/M assembly-language programs end with the 
statement: 

END 100H 

resulting in the default starting address of 100H (beginning of the transient program 
area). 
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3.4.3 The EQU Directive 

The EQU (equate) statement is used to set up synonyms for particular numeric ^ 
values. The EQU statement takes the form: 


label EQU expression 

CNMi 

where the label must be present and must not label any other statement. The assembler 
evaluates the expression and assigns this value to the identifier given in the label field. 
The identifier is usually a name that describes the value in a more human-oriented*^ 
manner. Further, this name is used throughout the program to place parameters on 
certain functions. Suppose data received from a teletype appears on a particular input 
port, and data is sent to the teletype through the next output port in sequence. Foft«^ 
example, you can use this series of equate statements to define these ports for l 
particular hardware environment: 

TTYBASE EQU 10H 5BASE PORT NUMBER FOR TTY ^ 


TTY IN 
TTYOUT 


EQU TTYBASE 
EQU TTYBASE+1 


5TTY DATA IN 


;tty data out 


At a later point in the program, the statements that access the teletype can appear 
follows: 


IN 


TTYIN 


5READ TTY DATA TO REG-A 




OUT TTYOUT 5WRITE DATA TO TTY FROM REG-* 

making the program more readable than if the absolute I/O ports are used. Further, if 
the hardware environment is redefined to start the teletype communications ports a*"** 
7FH instead of 10H, the first statement need only be changed to 

TTYBASE EQU7FH 5BASE PORT NUMBER FOR TTY tmm> 

and the program can be reassembled without changing any other statements. 


fim4[ 
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3.4.4 The SET Directive 

The SET statement is similar to the EQU, taking the form: 
label SET expression 

except that the label can occur on other SET statements within the program. The 
expression is evaluated and becomes the current value associated with the label. Thus, 
the EQU statement defines a label with a single value, while the SET statement defines a 
value that is valid from the current SET statement to the point where the label occurs 
on the next SET statement. The use of the SET is similar to the EQU statement, but is 
used most often in controlling conditional assembly. 

3.4.5 The IF and ENDIF Directives 


The IF and ENDIF statements define a range of assembly-language statements that 
P®* are to be included or excluded during the assembly process. These statements take on 
the form: 




IF expression 

statement#l 

statement#2 




statement#n 

ENDIF 


jswi 
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When encountering the IF statement, the assembler evaluates the expression follow¬ 
ing the IF. All operands in the expression must be defined ahead of the IF statement. If 
the expression evaluates to a nonzero value, then statement# 1 through statement#n 
are assembled. If the expression evaluates to zero, the statements are listed but not 
assembled. Conditional assembly is often used to write a single generic program that 
includes a number of possible run-time environments, with only a few specific portions ’""f 
of the program selected for any particular assembly. The following program segments, 
for example, might be part of a program that communicates with either a teletype or a 
CRT console (but not both) by selecting a particular value for TTY before the assembly 


begins. 




TRUE 

EQU 

OFFFFH 

1 DEFINE VALUE OF TRUE 

FALSE 

EQU 

NOT TRUE 

5DEFINE VALUE OF FALSE 

1 

TTY 

EQU 

TRUE 

5TRUE IF TTY» FALSE IF CRT 

! 

TTYBASE 

EQU 

10H 

5BASE OF TTY I/O PORTS 

CRTBASE 

EQU 

20H 

5BASE OF CRT I/O PORTS 


IF 

TTY 

5ASSEMBLE RELATIVE TO 

ITTYBASE 

CONIN 

EQU 

TTYBASE 

CONSOLE INPUT 

CONOUT 

EQU 

TTYBASE+1 

CONSOLE OUTPUT 


END IF 



1 

IF 

NOT TTY 

?ASSEMBLE RELATIVE TO 
1CRTBASE 

CONIN 

EQU 

CRTBASE 

CONSOLE INPUT 

CONOUT 

EQU 

CRTBASE+1 

iCONSOLE OUTPUT 


END IF 




«11 

IN 

CONIN 

iREAD CONSOLE DATA 


OUT 

CONTOUT 

5WRITE CONSOLE DATA 








In this case, the program assembles for an environment where a teletype is connected, 
based at port 10H. The statement defining TTY can be changed to 


TTY EQU FALSE 

arid, in this case, the program assembles for a CRT based at port 20H. 
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3.4.6 


The DB Directive 


■m The DB directive allows the programmer to define initialized storage areas in single- 
t precision byte format. The DB statement takes the form: 


label DB e#l, e#2,. . . , e#n 


where e#l through e#n are either expressions that evaluate to 8-bit values (the high- 
order bit must be zero) or are ASCII strings of length no greater than 64 characters. 
P® There is no practical restriction on the number of expressions included on a single 
source line. The expressions are evaluated and placed sequentially into the machine 
code file following the last program address generated by the assembler. String charac- 
p** ters are similarly placed into memory starting with the first character and ending with 
~ the last character. Strings of length greater than two characters cannot be used as 
operands in more complicated expressions. 


' - Note: ASCII characters are always placed in memory with the parity bit reset (0). 

Also, there is no translation from lower- to upper-case within strings. The optional 
label can be used to reference the data area throughout the remainder of the program. 
The following are examples of valid DB statements: 



data: 

DB 

0 1 1 *2 *3 tU *5 

pan 


DB 

data and Offh,5 ,377Q >1+2 + 3 + 4 


sign-on: 

DB 

'please type your name' * c r 1 1 f 



DB 

'AB 'SHR 8 > ' C ' * ' DE ' * AND 7FH 


3.4.7 The DW Directive 

p* The DW statement is similar to the DB statement except double-precision two-byte 
words of storage are initialized. The DW statement takes the form: 



i 


label 


DW e#l, e#2,. . . , e#n 




where e#l through e#n are expressions that evaluate to 16-bit results. Note that ASCII 
strings of one or two characters are allowed, but strings longer than two characters are 
disallowed. In all cases, the data storage is consistent with the 8080 processor; the least 
significant byte of the expression is stored first in memory, followed by the most 
significant byte. The following are examples of DW statements: 


doub: DN 0 f f e f h * d o u b + 4 * s i 3n o n -$ #255 + 255 

DM 'a' > 5 > ' a b ' > ' C D ' tGshl 8 or lib* 
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3.4.8 The DS Directive 

The DS statement is used to reserve an area of uninitialized memory, and takes the fe 
form: 

label 


DS 


expression 




where the label is optional. The assembler begins subsequent code generation after the 
area reserved by the DS. Thus, the DS statement given above has exactly the same effect 
as the following statement: i 


label: EQU $ 5LABEL VALUE IS CURRENT CODE LOCATION 

ORG $+expression MOVE PAST RESERVED AREA 


mm 


3.5 Operation Codes _ 

Assembly-language operation codes form the principal part of assembly-language 
programs and form the operation field of the instruction. In general, ASM accepts all 
the standard mnemonics for the Intel 8080 microcomputer, which are given in detail in*®^ 
the Intel 8080 Assembly Language Programming Manual. Labels are optional on each 
input line. The individual operators are listed briefly in the following sections for 
completeness, although the Intel manuals should be referenced for exact operator®*^ 
details. In Tables 3-4 through 3-8, bit values have the following meaning: 

■ e3 represents a 3-bit value in the range 0-7 that can be one of the predefined ^*^ 
registers A, B, C, D, E, H, L, M, SP, or PSW. 

■ e8 represents an 8-bit value in the range 0-255. 

■ el6 represents a 16-bit value in the range 0-65535. 

These expressions can be formed from an arbitrary combination of operands and 
operators. In some cases, the operands are restricted to particular values within thep?^ 
allowable range, such as the PUSH instruction. These cases are noted as they are 
encountered. 

In the sections that follow, each operation code is listed in its most general form,*"^ 
along with a specific example, a short explanation, and special restrictions. 

UhJI 
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3.5.1 Jumps, Calls, and Returns 

The Jump, Call, and Return instructions allow several different forms that test the 
condition flags set in the 8080 microcomputer CPU. The forms are shown in Table 3-4. 


Table 3-4. Jumps, Calls, and Returns 


pii 

Form 

Bit 

Value 

Example 

Meaning 


JMP 

el 6 

JMP LI 

Jump unconditionally to label 

jwNpq 

JNZ 

el6 

JNZ LZ 

Jump on nonzero condition to 
label 

r 

JZ 

el6 

JZ100H 

Jump on zero condition to label 

r 

JNC 

el6 

JNC Ll+4 

Jump no carry to label 

JC 

el6 

JC L3 

Jump on carry to label 

juP'IHfr 

JPO 

el6 

JPO $ + 8 

Jump on parity odd to label 


JPE 

el6 

JPE L4 

Jump on even parity to label 

pi* 

JP 

el6 

JP GAMMA 

Jump on positive result to label 


JM 

el6 

JM al 

Jump on minus to label 

|PS5 

CALL 

el6 

CALL SI 

Call subroutine unconditionally 


CNZ 

el6 

CNZ S2 

Call subroutine on nonzero con¬ 
dition 

ppm) 

CZ 

el6 

CZ 100H 

Call subroutine on zero condition 


CNC 

el6 

CNC Sl+4 

Call subroutine if no carry set 

r 

CC 

el6 

CC S3 

Call subroutine if carry set 


CPO 

el6 

CPO $ + 8 

Call subroutine if parity odd 


S3 DIGITAL RESEARCH 


3-17 





3.5 Operation Codes 


CP/M Operating System Manual 


Table 3-4. (continued) 


Form 

Bit 

Value 

Example 

Meaning 

CPE 

el 6 

CPE $4 

Call subroutine if parity even 

CP 

el6 

CP GAMMA 

Call subroutine if positive result 

CM 

el6 

CM b 1 $c2 

Call subroutine if minus flag 

RST 

e3 

RST 0 

Programmed restart, equivalent 
to CALL 8*e3, except one byte 
call 

RET 



Return from subroutine 

RNZ 



Return if nonzero flag set 

RZ 



Return if zero flag set 

RNC 



Return if no carry 

RC 



Return if carry flag set 

RPO 



Return if parity is odd 

RPE 



Return if parity is even 

RP 



Return if positive result 

RM 



Return if minus flag is set 






fwiil 








6M( 


MW| 






(S*|f 
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3.5.2 Immediate Operand Instructions 

Several instructions are available that load single- or double-precision registers or 
single-precision memory cells with constant values, along with instructions that 
perform immediate arithmetic or logical operations on the accumulator (register A). 
Table 3-5 describes the immediate operand instructions. 


Table 3-5. Immediate Operand Instructions 


Form with 

Bit Values 

Example 

Meaning 

MVI e3,e8 

MM IB >255 

Move immediate data to register A, 
B, C, D, E, H, L, or M (memory) 

ADI e8 

ADI 1 

Add immediate operand to A with¬ 
out carry 

ACIe8 

AC I OFFH 

Add immediate operand to A with 
carry 

SUIe8 

SU I L + 3 

Subtract from A without borrow 
(carry) 

SBI e8 

SBI L AND 1 IB 

Subtract from A with borrow (car¬ 
ry) 

ANI e8 

ANI $ AND 7FH 

Logical a nd A with immediate data 

XRI e8 

XRI 1 1 1 1$0000B 

Exclusive or A with immediate data 

ORI e8 

ORI L AND 1 + 1 

Logical or A with immediate data 

CPI e8 

CPI ' a ' 

Compare A with immediate data, 
same as SUI except register A not 
changed. 

LXI e3,el6 

LXI B 1 100H 

Load extended immediate to register 
pair. e3 must be equivalent to B, D, 
H, or SP. 
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3.5.3 Increment and Decrement Instructions 

The 8080 provides instructions for incrementing or decrementing single- and double- imm 
precision registers. The instructions are described in Table 3-6. 


Table 3-6. Increment and Decrement Instructions 


Form with 
Bit Value 

Example 

Meaning 

INR e3 

INR E 

Single-precision increment register. 
e3 produces one of A, B, C, D, E, H, 
L, M. 

DCR e3 

DCR A 

Single-precision decrement register. 
e3 produces one of A, B, C, D, E, H, 
L,M. 

INX e3 

INX SP 

Double-precision increment register 
pair. e3 must be equivalent to B, D, 
H, orSP. 

DCXe3 

DCX B 

Double-precision decrement register 
pair. e3 must be equivalent to B, D, 
H, orSP. 






SiMf 


fMlj 
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3.5.4 Data Movement Instructions 

Instructions that move data from memory to the CPU and from CPU to memory are 
given in the following table. 


Table 3-7. Data Movement Instructions 


Form with 
Bit Value 

Example 

Meaning 

MOV e3,e3 

MOV A #B 

Move data to leftmost element from 
rightmost element. e3 produces on 
of A, B, C, D, E, H, L, or M. MOV 
M,M is disallowed. 

LDAX e3 

LDAX B 

Load register A from computed 
address. e3 must produce either B or 
D. 

STAX e3 

STAX D 

Store register A to computed 
address. e3 must produce either B or 
D. 

LHLD el6 

LHLD LI 

Load HL direct from location el6. 
Double-precision load to H and L. 

SHLD el6 

SHLD L5 + x 

Store HL direct to location el6. 
Double-precision store from H and 

L to memory. 

LDAel6 

LDA Gamma 

Load register A from address el6. 

STA el6 

STA X3-5 

Store register A into memory at el6. 

POP e3 

POP PSW 

Load register pair from stack, set SP. 
e3 must produce one of B, D, H, or 
PSW. 

PUSH e3 

PUSH B 

Store register pair into stack, set SP. 
e3 must produce on of B, D, H, or 
PSW. 
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mmM 


Table 3-7. (continued) 


Form with 
Bit Value 

Example 

Meaning 

IN e8 

IN 0 

Load register A with data from port 
e8. 

OUT e8 

OUT 255 

Send data from register A to port e8. 

XTHL 


Exchange data from top of stack 
with HL. 

PCHL 


Fill program counter with data from 
HL. 

SPHL 


Fill stack pointer with data from 
HL. 

XCHG 


Exchange DE pair with HL pair. 


3.5.5 Arithmetic Logic Unit Operations 

Instructions that act upon the single-precision accumulator to perform arithmetic 
and logic operations are given in the following table. 


Table 3-8. Arithmetic Logic Unit Operations 


Form with 
Bit Value 

Example 

Meaning 

ADD e3 

ADD B 

Add register given by e3 to accumu¬ 
lator without carry. e3 must pro¬ 
duce one of A, B, C, D, E, H, or L. 

ADC e3 

ADC L 

Add register to A with carry, e3 as 
above. 

SUB e3 

SUB H 

Subtract reg e3 from A without car¬ 
ry, e3 is defined as above. 
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Table 3-8. (continued) 


Form with 
Bit Value 

Example 

Meaning 

SBB e3 

SBB 2 

Subtract register e3 from A with carry, 
e3 defined as above. 

ANA e3 

ANA 1 + 1 

Logical and reg with A, e3 as above. 

XRA e3 

XRA A 

Exclusive or with A, e3 as above. 

ORA e3 

□ RA B 

Logical or with A, e3 defined as above. 

CMP e3 

CMP H 

Compare register with A, e3 as above. 

DAA 


Decimal adjust register A based upon 
last arithmetic logic unit operation. 

CMA 


Complement the bits in register A. 

STC 


Set the carry flag to 1. 

CMC 


Complement the carry flag. 

RLC 


Rotate bits left, (re)set carry as a side 
effect. High-order A bit becomes carry. 

RRC 


Rotate bits right, (re)set carry as side 
effect. Low-order A bit becomes carry. 

RAL 


Rotate carry/A register to left. Carry is 
involved in the rotate. 

RAR 


Rotate carry/A register to right. Carry is 
involved in the rotate. 

DAD e3 

DAD B 

Double-precision add register pair e3 to 
HL. e3 must produce B, D, H, or SP. 
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3.5.6 Control Instructions 

The four remaining instructions, categorized as control instructions, are the follow¬ 
ing: 

■ HLT halts the 8080 processor. 

■ DI disables the interrupt system. 

■ El enables the interrupt system. 

■ NOP means no operation. 

3.6 Error Messages 

When errors occur within the assembly-language program, they are 
character flags in the leftmost position of the source listing. The line 
echoed at the console so that the source listing need not be examined 
errors are present. The error codes are listed in the following table. 


listed as single¬ 
in error is also 
to determine if 


Table 3-9. Error Codes 


Error Code 

Meaning 

D 

Data error: element in data statement cannot be placed in the spe¬ 
cified data area. 

E 

Expression error: expression is ill-formed and cannot be computed at 
assembly time. 

L 

Label error: label cannot appear in this context; might be duplicate 
label. 

N 

Not implemented: features that will appear in future ASM versions. 
For example, macros are recognized, but flagged in this version. 

0 

Overflow: expression is too complicated (too many pending oper¬ 
ators) to be computed and should be simplified. 

P 

Phase error: label does not have the same value on two subsequent 
passes through the program. 
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(IfflPPS 


3.7 A Sample Session 

The following sample session shows interaction with the assembler and debugger in 
the development of a simple assembly-language program. They'arrow represents a 
carriage return keystroke. 

A >ASM SORT y Assemble SORT.ASM 

CP/M ASSEMBLER - MER 1,0 mi 

0015C Next free address 

003H USE FACTOR Percent of table used 00 to ff (hexadecimal) 

END OF ASSEMBLY 


A >DIR SORT.*/ 

SORT ASM Source file 

SORT BAK Back-up from last edit 

SORT PRN Print file (contains tab characters) 

SORT HEX Machine code file 

A >TYPE SORT* PRN/ 

Source line 

I-*-1 

; SORT PROGRAM IN CP/M ASSEMBLY LANGUAGE 

j START AT THE BEGINNING OF THE TRANSIENT 

PROGRAM AREA 

Machine code location 

0100-*-^ 0RG 100H 

Generated machine code 


0100 ZlASOr'SORT: 

LXI H>SH 

5ADDRESS SNITCH TOGGLE 

0103 3G01 


MM I M»1 

5SET TO 1 FOR FIRST ITERATION 

0105 214701 


LXI H>I 

5ADDRESS INDEX 

0108 3600 


MM I M»0 

51=0 


5 

COMPARE I 

NITH ARRAY SIZE 

010A 7E 

C0MPL: 

MOM A >M 

5A REGISTER = I 

010B FE09 


CPI N-l 

5CY SET IF I<(N-1) 

010D 021901 


JNC C0NT 

?CONTINUE IF I<=(N-2) 


5 

5 

END OF ONE 

: PASS THROUGH DATA 


fiBUf 
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0110 214601 
0113 7EB7C200001 


LXI h,sn ;check for zero snitches 

MOO A.♦ M! ORA A! JNZ SORT !END OF SORT IF SN=0 


0118 FF 


RST 7 5G0 TO THE DEBUGGER INSTEAD OF REB 


Truncated 1 
0119 \ 

5F16002148C0NT s 
0121 4E79234G 


CONTINUE THIS PASS 

ADDRESSING I, SO LOAD A0(I) INTO REGISTERS 

MOO E, A! MOI D t 0! LXI H, AO! DAD D! DAD D 

MOO C, M! MOO A t C! INK H! MOO B t M 

LON ORDER BYTE IN A AND C, HIGH ORDER BYTE IN B 


5 MOO H AND L TO ADDRESS A0(I+1) 

0125 23 INK H 


? COMPARE OALUE NITH REGS CONTAINING AO (I) 

012G 9G5778239E SUB M! MOO D, A! MOO A, B! INK H! SBB M ^SUBTRACT 


l BORRON SET IF A0(1+1)>A0(I) 

012B DA3F01 JC INCI 5SKIP IF IN PROPER ORDER 


012E B2CA3F01 
0132 5S702B5E 
013G 712B722B73 


CHECK FOR EQUAL OALUES 

ORA D! JZ INCI 5SKIP IF AO(I) = A0(I+1) 

MOO D, M! MOO M, B! DCX H! MOO E, M 

MOO M t C! DCX H! MOO M, D! DCX H! MOO M, E 


; INCREMENT SNITCH COUNT 

013B 21460134 LXI H,SN! INR M 


; INCREMENT I 

013F 21470134C3INCI:LXI Htl! INR M! JMP COMP 


l DATA DEFINITION SECTION 

014G 00 SN; DB 0 5RESER0E SPACE FOR SNITCH COUNT 

0147 I: DS 1 5SPACE FOR INDEX 

0148 0500G4001EA0: DN 5, 100, 30, 50, 20, 7, 1000, 300, 100, -327G7 
OOOA =^N EQU($-A0)/2 ICOMPUTE N INSTEAD OF PRE 

015C ^'\^END 

A >TYPE SDR T * HE>(^ Eq u a te value 
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: 100100002146013G012147013G007EFE09D2190140~| Mac h ine CO( j e in 
: 10011000214B017EB7C20001FF5F1S002148011988 > H£X f ormat 
:10012000194E792346239G5778239EDA3F01B2CAA7J 

:100130003F0156702B5E712B722B732146013421C7“ 

:07014000470134C30A0100GE 
:100148000500G4001E00320014000700E8032C01BB 
:0401580064000180BE 
:0000000000 

A >DDT SORT*HEX/ Start debug run 

1GK DDT UER 1.0 
NEXT PC 

015C 0000 Default address (no address on END statement) 

-XP/ 

P=0000 100 Change PC to 100 


I Machine code in 
f HEX format 


- UFFFF/ Untrace for 65535 steps 
D=0000 


Abort with rubout,. 

S=0100 P=0100 LXI H >0146*0100 


H=0000 


C0Z0M0E0I0 A=00 B=0000 
-T10/ Trace 10 16 steps 

C0Z0M0E0I0 A=01 B=0000 
C0Z0M0E0I0 A=01 B=0000 
COZOMOEOIO A=01 B=0000 
C0Z0M0E0I0 A=01 B=0000 
COZOMOEOIO A=01 B=0000 
COZOMOEOIO A=00 B=0000 
C1Z0M1E0I0 A=00 B=0000 
C1Z0M1E0I0 A=00 B=0000 
C1Z0M1E0I0 A=00 B=0000 
C1Z0M1E0I0 A=01 B=0000 
COZOMOEOIO A=01 B=0000 
COZOMOEOIO A=01 B=0000 
COZOMOEOIO A=01 B=0000 
COZOMOEOIO A=01 B=0000 
COZOMOEOIO A=01 B=0000 
COZOMOEOIO A=01 B=0000 
-AIQD 


D=0000 H=014G S=0100 
D=0000 H=014G S=0100 
D=0000 H=0146 S=0100 
D=0000 H=0147 S=0100 
D=0000 H=0147 S=0100 
D=0000 H=0147 S=0100 
D=0000 H=0147 S=0100 
D=0000 H=0147 S=0100 
D=0000 H=0146 S=0100 
D=0000 H=014G S=0100 
D=0000 H=0146 S=0100 
D=0000 H=0146 S=0100 
D=0000 H=0146 S=0100 
D=0000 H=0146 S=0100 
D=0000 H=0147 S=0100 
D=0000 H=0147 S=0100 


P=0100 

LX I 

H# 

0146 

P-0103 

M01 

M> 

01 

P=0105 

LX I 

Ht 

0147 

9? 

o 

ii 

OL_ 

M01 

M t 

00 

P=010A 

MOO 

A # 

M 

P=010B 

CPI 

09 


P=010D 

JNC 

0119 

P=0110 

LX I 

Ht 

014G 

P=0113 

MOO 

A t 

M 

P=0114 

ORA 

A 


P=0115 

JNZ 

0100 

P=0100 

LX I 

Ht 

014G 

P=0103 

MO I 

M» 

01 

P=0105 

LX I 

Ht 

0147 

CD 

O 

O 

II 

o_ 

MO I 

M» 

00 

P=010A 

MOO 

A» 

M*010B 

Stopped at 

iobh/ 



iMM 
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010D JC 119/ Change to a jump on carry 
0110/ 

-XP/ 

P=010B 100/ Reset program counter back to beginning of program 



- TtQ / Trace execution for 10H 

steps 



pSKj 









C0Z0M0E0I0 

A=00 

B=0000 

D=0000 

H=0147 

S=0100 

P=0100 


C0Z0M0E0I0 

A=00 

B=0000 

D=0000 

H=014G 

S=0100 

P=0103 


C0Z0M0E0I0 

A=00 

B=0000 

D=0000 

H=0146 

S=0100 

P=0105 


C0Z0M0E0I0 

A=00 

B=0000 

D=0000 

H=0147 

S=0100 

P=0108 


C0Z0M0E0I0 

A=00 

B=0000 

D=0000 

H=0147 

S=0100 

P=010A 


C0Z0M0E0I0 

A=00 

B=0000 

D=0000 

H=0147 

S=0100 

P=010B 


C1Z0M1E0I0 

A=00 

B=0000 

D=0000 

H=0147 

S=0100 

P=010D 


C1Z0M1E0I0 

A=00 

13=0000 

D=0000 

H=0147 

S=0100 

P=0119 


C1Z0M1E0I0 

A=00 

B=0000 

D=0000 

H=0147 

S=0100 

P=011A 


C1Z0M1E0I0 

A=00 

B=0000 

D=0000 

H=0147 

S=0100 

P=011C 


C1Z0M1E0I0 

A=00 

B=0000 

D=0000 

H=0148 

S=0100 

P=011F 


C0Z0M1E0I0 

A=00 

B=0000 

D=0000 

H=0148 

S=0100 

P=0120 

— 

C0Z0M1E0I0 

A=00 

B=0000 

D=0000 

H=0148 

S=0100 

P=0121 


C0Z0M1E0I0 

A=00 

B=0005 

D=0000 

H=0148 

S=0100 

P=0122 


C0Z0M1E0I0 

A=05 

B=0005 

D=0000 

H=0148 

S=0100 

P=0123 

. 

C0Z0M1E0I0 

A=05 

B=0005 

D=0000 

H=0149 

S=0100 

P=0124 


Altered instruction 


A *M 
09 


MOM E *A 
MMI D *00 
LXI H *0148 
DAD D 
DAD D 
MOM C *M 
MOM A *C 



-Lioty 



0100 

LXI 


0103 

MM I 


0105 

LXI 

|^t 

0108 

MM I 

-— 

010A 

MOM 


010B 

CPI 


010D 

JC 


0110 

LXI 


0113 

MOM 


0114 

ORA 

0115 

JNZ 


Automatic breakpoint* 




09 

0119 
H *014 
A *M 
A 


List some code 
from 100H 


-v 
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0118 

RST 

07 

0118 

M0U 

E,A 

011A 

M01 

D #00 

one 

LX I 

o 

■Cs 

CD 

Abort 

list 

with n 


List more 


- GfllB / Start program from current PC (0125H) and run in real time to 11BH 


*0127 Stopped with an external interrupt 7 from front panel 
-T4/ (program was looping indefinitely) 

Look at looping program in trace mode^ 

C0Z0M0E0I0 A=38 B=0064 D=000G H=015G S=0100 P=0127 MOO D»A 
C0Z0M0E0I0 A=38 B=0064 D=380G H=015G S=0100 P=0128 MOO A»B 
C0Z0M0E0I0 A=00 B=00G4 D=380G H=015G S=0100 P=0129 INK H 
C0Z0M0E0I0 A=00 B=00G4 D=380G H=0157 S=0100 P=012A SBB M*012B 
-DU1B/ 

/Data are sorted, but program does not stop. 
0148 05 00 07 00 14 00 IE 00f.. 

0150 32 00 64 00 G4 00 2C 01 E8 03 01 80 00 00 00 00 2*D,D« .. 

0160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00. 

-GO / Return to CP/M 

A >DDT SORT,HEXy Reload the memory image 

1GK DDT 0ER 1*0 
NEXT PC 
015C 0000 
-XP 

P=0000 100/ Set PC to beginning of program 

-LI00/ List bad OPCODE 

010D JNC 01 lS^ 

0110 LXI Ht0ias 

-Abort list with rubout 
-A10D / Assemble new OPCODE 
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010D JC 113/ 


0110/ 


jSli*j 


-LlQ0f List starting section of program 

0100 LXI H»0146 

0103 M01 M *01 

0105 LXI H >0147 

0108 M01 M >00 

-Abort list with rubout 
-A103/ Change switch initialization to 00 

0103 M0I MiO/ 


- A C Return to CP/M with CTRL-C (GO works as well) 

— SA0E 1 S0RT.C0M/ Save 1 page (256 bytes, from 100H to IffH) on disk in case 
there is need to reload later 

_ A >DDT SORT*COM/ Restart DDT with saved memory image 

1GK DDT 0ER 1.0 
NEXT PC 

P" 0200 0100 COM file always starts with address 100H 
- G / Run the program from PC = 100H 

*0118 Programmed stop (RST 7) encountered 
' - -DU1B 


pm 


0148 05 00 07 00 14 00 
0150 32 00 84 00 84 00 


.Data properly sorted 
IE 00% . 

2C 01 E8 03 01 80 00 00 00 00 2.D.D. 


♦ ♦♦♦♦♦♦ 


P* 0180 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00. 

0170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00. 


P®* -GO /Return to CP/M 
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A>E0 SORTtASM^ Make changes to original program 

(The caret,", indicates a control character) 


*NfO 'ZOTT y Find next ,0 
MV I MfO 


;i = o 


*-y Up one line in text 

LX I Hfl ?ADDRESS INDEX 


*-y Up another line 

MVI Mtl ?SET TO 1 FOR FIRST ITERATION 


*KT yK ill line and type next line 


LX I 


H»I 5ADDRESS INDEX 


* Jy Insert new line 

MVI M >0 iZERO SW 



H fl 5ADDRESS INDEX 


*NJNC ZOT y 
JNC*Ty 

CONTy !CONTINUE IF KXN-2) 


* -2DIC ZOLT / 

JC CONT 5CONTINUE IF I<=(N-2) 


*E/ |-Source from disk A 

-HEX to disk A 

b>ASM SORTiAAZp -Skip PRN file 

CP/M ASSEMBLER - VER 1.0 

015C Next address to assemble 
003H USE FACTOR 
END OF ASSEMBLY 
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r 1GK DDT VER 1.0 
NEXT PC 
015C 0000 
- 0100 / 


3.7 A Sample Session 




*0118 

-DU\8/ 

^Data sorted 

0148 05 00 07 00 14 00 IE 00. 

0150 32 00 64 00 64 00 2C 01 E8 03 01 80 00 00 00 00 2.D.D 

0160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00. 


* » » I I I I 

******* 


-Abort with rubout 

-GO/ Return to CP/M—program checks OK. 


End of Section 3 


pHPt 

|®Pil 

pum 

pm 
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Section 4 

CP/M Dynamic Debugging Tool 


fflBUI 

4.1 Introduction 


pfPJ 


The DDT program allows dynamic interactive testing and debugging of programs 
generated in the CP/M environment. Invoke the debugger with a command of one of 
the following forms: 


pwi 

pfPJ 


DDT 

DDT filename.HEX 
DDT filename.COM 


where filename is the name of the program to be loaded and tested. In both cases, the 
DDT program is brought into main memory in place of the Console Command Proces¬ 
sor (CCP) and resides directly below the Basic Disk Operating System (BDOS) portion 
of CP/M. Refer to Section 5 for standard memory organization. The BDOS starting 
address, located in the address field of the JMP instruction at location 5H, is altered to 
reflect the reduced Transient Program Area (TPA) size. 


The second and third forms of the DDT command perform the same actions as the 
first, except there is a subsequent automatic load of the specified HEX or COM file. 
The action is identical to the following sequence of commands: 


DDT 

f** Ifilename.HEX or Ifilename.COM 
R 


jiippft 

|®ppi 


where the I and R commands set up and read the specified program to test. See the 
explanation of the I and R commands below for exact details. 

Upon initiation, DDT prints a sign-on message in the form: 

DDT VER m.m 

where m.m is the revision number. 
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Following the sign-on message, DDT prompts you with the hyphen character, and 
waits for input commands from the console. You can type any of several single¬ 
character commands, followed by a carriage return to execute the command. Each line 
of input can be line-edited using the following standard CP/M controls: 


Table 4-1. Line-editing Controls 


Control 

Result 

rubout 

removes the last character typed 

CTRL-U 

removes the entire line, ready for retyping 

CTRL-C 

reboots system 


Any command can be up to 32 characters in length. An automatic carriage return is 
inserted as character 33, where the first character determines the command type. Table 
4-2 describes DDT commands. 


Table 4-2. DDT Commands 


Command 

Character 

Result 

A 

enters assembly-language mnemonics with operands. 

D 

displays memory in hexadecimal and ASCII. 

F 

fills memory with constant data. 

G 

begins execution with optional breakpoints. 

I 

sets up a standard input File Control Block. 

L 

lists memory using assembler mnemonics. 

M 

moves a memory segment from source to destination. 

R 

reads a program for subsequent testing. 


4-2 


m DIGITAL RESEARCH 





CP/M Operating System Manual 


4.1 Introduction 


Table 4-2. (continued) 


Command 

Character 

Result 

s 

substitutes memory values. 

T 

traces program execution. 

U 

untraced program monitoring. 

X 

examines and optionally alters the CPU state. 


The command character, in some cases, is followed by zero, one, two, or three hexadec¬ 
imal values, which are separated by commas or single blank characters. All DDT 
numeric output is in hexadecimal form. The commands are not executed until the 
carriage return is typed at the end of the command. 

At any point in the debug run, you can stop execution of DDT by using either a 
CTRL-C or GO (jump to location 0000H) and save the current memory image by using 
a SAVE command of the form: 

SAVE n filename. COM 

where n is the number of pages (256 byte blocks) to be saved on disk. The number of 
blocks is determined by taking the high-order byte of the address in the TPA and 
converting this number to decimal. For example, if the highest address in the TPA is 
134H, the number of pages is 12H or 18 in decimal. You could type a CTRL-C during 
the debug run, returning to the CCP level, followed by 

SAME 18 X# COM 

The memory image is saved as X ♦ CDM on the disk and can be directly executed by 
typing the name X. If further testing is required, the memory image can be recalled by 
typing 

DDT X ♦ COM 

which reloads the previously saved program from location 100H through page 18, 
23FFH. The CPU state is not a part of the COM file; thus, the program must be 
restarted from the beginning to test it properly. 
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4.2 DDT Commands 

The individual commands are detailed below. In each case, the operator must wait 
for the hyphen prompt character before entering the command. If control is passed to a 
program under test, and the program has not reached a breakpoint, control can be 
returned to DDT by executing a RST 7 from the front panel. In the explanation of each 
command, the command letter is shown in some cases with numbers separated by 
commas, the numbers are represented by lower-case letters. These numbers are always 
assumed to be in a hexadecimal radix and from one to four digits in length. Longer 
numbers are automatically truncated on the right. 

Many of the commands operate upon a CPU state that corresponds to the program 
under test. The CPU state holds the registers of the program being debugged and 
initially contains zeros for all registers and flags except for the program counter, P, and 
stack pointer, S, which default to 100H. The program counter is subsequently set to the 
starting address given in the last record of a HEX file if a file of this form is loaded, see 
the I and R commands. 

4.2.1 The A (Assembly) Command 

DDT allows in-line assembly language to be inserted into the current memory image 
using the A command, which takes the form: 

As 

where s is the hexadecimal starting address for the in-line assembly. DDT prompts the 
console with the address of the next instruction to fill and reads the console, looking for 
assembly-language mnemonics followed by register references and operands in abso¬ 
lute hexadecimal form. See the Intel 8080 Assembly Language Reference Card for a list 
of mnemonics. Each successive load address is printed before reading the console. The 
A command terminates when the first empty line is input from the console. 

Upon completion of assembly language input, you can review the memory segment 
using the DDT disassembler (see the L command). 

Note that the assembler/disassembler portion of DDT can be overlaid by the tran¬ 
sient program being tested, in which case the DDT program responds with an error 
condition when the A and L commands are used. 
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4.2.2 The D (Display) Command 

The D command allows you to view the contents of memory in hexadecimal and 
ASCII formats. The D command takes the forms: 

D 

Ds 

Ds,f 

In the first form, memory is displayed from the current display address, initially 
100H, and continues for 16 display lines. Each display line takes the followng form: 

aaaa bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb cccccccccccccccc 

where aaaa is the display address in hexadecimal and bb represents data present in 
memory starting at aaaa. The ASCII characters starting at aaaa are to the right (repre¬ 
sented by the sequence of character c) where nongraphic characters are printed as a 
period. You should note that both upper- and lower-case alphabetics are displayed, and 
will appear as upper-case symbols on a console device that supports only upper-case. 
Each display line gives the values of 16 bytes of data, with the first line truncated so that 
the next line begins at an address that is a multiple of 16. 

The second form of the D command is similar to the first, except that the display 
address is first set to address s. 

The third form causes the display to continue from address s through address f. In all 
cases, the display address is set to the first address not displayed in this command, so 
that a continuing display can be accomplished by issuing successive D commands with 
no explicit addresses. 

Excessively long displays can be aborted by pressing the return key. 

4.2.3 The F (Fill) Command 

The F command takes the form: 

Fs,f,c, 

where s is the starting address, f is the final address, and c is a hexadecimal byte 
constant. DDT stores the constant c at address s, increments the value of s and test 
against f. If s exceeds f, the operation terminates, otherwise the operation is repeated. 
Thus, the fill command can be used to set a memory block to a specific constant value. 
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4.2.4 The G (Go) Command 

A program is executed using the G command, with up to two optional breakpoint 
addresses. The G command takes the forms: 

G 

Gs 

Gs,b 

Gs,b,c 

G,b 

G,b,c 

The first form executes the program at the current value of the program counter in 
the current machine state, with no breakpoints set. The only way to regain control in 
DDT is through a RST 7 execution. The current program counter can be viewed by 
typing an X or XP command. 

The second form is similar to the first, except that the program counter in the current 
machine state is set to address s before execution begins. 

The third form is the same as the second, except that program execution stops when 
address b is encountered (b must be in the area of the program under test). The 
instruction at location b is not executed when the breakpoint is encountered. 

The fourth form is identical to the third, except that two breakpoints are specified, 
one at b and the other at c. Encountering either breakpoint causes execution to stop, 
and both breakpoints are cleared. The last two forms take the program counter from 
the current machine state and set one and two breakpoints, respectively. 

Execution continues from the starting address in real-time to the next breakpoint. 
There is no intervention between the starting address and the break address by DDT. If 
the program under test does not reach a breakpoint, control cannot return to DDT 
without executing a RST 7 instruction. Upon encountering a breakpoint, DDT stops 
execution and types 

*d 
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where d is the stop address. The machine state can be examined at this point using the 
X (Examine) command. You must specify breakpoints that differ from the program 
counter address at the beginning of the G command. Thus, if the current program 
counter is 1234H, then the following commands: 

G 1 1234 
G400 ,400 

both produce an immediate breakpoint without executing any instructions. 

4.2.5 The I (Input) Command 

The I command allows you to insert a filename into the default File Control Block 
(FCB) at 5CH. The FCB created by CP/M for transient programs is placed at this 
location (see Section 5). The default FCB can be used by the program under test as if it 
had been passed by the CP/M Console Processor. Note that this filename is also used by 
DDT for reading additional HEX and COM files. The I command takes the forms: 

Ifilename 

Ifilename.typ 

If the second form is used and the filetype is either HEX or COM, subsequent 
R commands can be used to read the pure binary or hex format machine code. 
Section 4.2.8 gives further details. 

4.2.6 The L (List) Command 

The L command is used to list assembly-language mnemonics in a particular pro¬ 
gram region. The L command takes the forms: 

L 

Ls 

Ls,f 

The first form lists twelve lines of disassembled machine code from the current list 
address. The second form sets the list address to s and then lists twelve lines of code. 
The last form lists disassembled code from s through address f. In all three cases, the list 
address is set to the next unlisted location in preparation for a subsequent L command. 
Upon encountering an execution breakpoint, the list address is set to the current value 
of the program counter (G and T commands). Again, long typeouts can be aborted by 
pressing RETURN during the list process. 
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4.2.7 The M (Move) Command 

The M command allows block movement of program or data areas from one loca¬ 
tion to another in memory. The M command takes the form: 

Ms,f,d 

where s is the start address of the move, f is the final address, and d is the destination 
address. Data is first removed from s to d, and both addresses are incremented. If s 
exceeds f, the move operation stops; otherwise, the move operation is repeated. 

4.2.8 The R (Read) Command 

The R command is used in conjunction with the I command to read COM and HEX 
files from the disk into the transient program area in preparation for the debug run. The 
R command takes the forms: 

R 

Rb 

where b is an optional bias address that is added to each program or data address as it 
is loaded. The load operation must not overwrite any of the system parameters from 
000H through OFFH (that is, the first page of memory). If b is omitted, then b = 0000 is 
assumed. The R command requires a previous 1 command, specifying the name of a 
HEX or COM file. The load address for each record is obtained from each individual 
HEX record, while an assumed load address of 100H is used for COM files. Note that 
any number of R commands can be issued following the I command to reread the 
program under test, assuming the tested program does not destroy the default area at 
5CH. Any file specified with the filetype COM is assumed to contain machine code in 
pure binary form (created with the LOAD or SAVE command), and all others are 
assumed to contain machine code in Intel hex format (produced, for example, with the 
ASM command). 

Recall that the command, 

DDT f i 1ename♦t yp 

which initiates the DDT program, equals to the following commands: 

DDT 

- I filename*typ 
-R 


4-8 


m DIGITAL RESEARCH 



CP/M Operating System Manual 


4.2 DDT Commands 


Whenever the R command is issued, DDT responds with either the error indicator ? 
(file cannot be opened, or a checksum error occurred in a HEX file) or with a load 
message. The load message takes the form: 


NEXT PC 
I** nnnn pppp 

where nnnn is the next address following the loaded program and pppp is the assumed 
pp* program counter (100H for COM files, or taken from the last record if a HEX file is 
specified). 




4.2.9 The S (Set) Command 

The S command allows memory locations to be examined and optionally altered. 
The S command takes the form: 

Ss 


where s is the hexadecimal starting address for examination and alteration of memory. 
DDT responds with a numeric prompt, giving the memory location, along with the 
data currently held in memory. If you type a carriage return, the data is not altered. If a 
byte value is typed, the value is stored at the prompted address. In either case, DDT 
continues to prompt with successive addresses and values until you type either a period 
or an invalid input value is detected. 



4.2.10 The T (Trace) Command 

The T command allows selective tracing of program execution for 1 to 65535 
program steps. The T command takes the forms: 

T 

Tn 

In the first form, the CPU state is displayed and the next program step is executed. 
The program terminates immediately, with the termination address displayed as 

*hhhh 


pppi* 


where hhhh is the next address to execute. The display address (used in the D com¬ 
mand) is set to the value of H and L, and the list address (used in the L command) is set 
to hhhh. The CPU state at program termination can then be examined using the X 
command. 
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The second form of the T command is similar to the first, except that execution is 
traced for n steps (n is a hexadecimal value) before a program breakpoint occurs. ^ 
breakpoint can be forced in the trace mode by typing a rubout character. The CPU stat< 
is displayed before each program step is taken in trace mode. The format of the display 
is the same as described in the X command. 

You should note that program tracing is discontinued at the CP/M interface and 
resumes after return from CP/M to the program under test. Thus, CP/M functions that 
access I/O devices, such as the disk drive, run in real-time, avoiding I/O timing prob pp " n 
lems. Programs running in trace mode execute approximately 500 times slower than 
real-time because DDT gets control after each user instruction is executed. Interrupt 
processing routines can be traced, but commands that use the breakpoint facility (G, T«^ 
and U) accomplish the break using an RST 7 instruction, which means that the testec 
program cannot use this interrupt location. Further, the trace mode always runs the 
tested program with interrupts enabled, which may cause problems if asynchronous ^ 
interrupts are received during tracing. 

To get control back to DDT during trace, press RETURN rather than executing an 
RST 7. This ensures that the trace for current instruction is completed before interrup' 5 ""^ 
tion. 


4.2.11 The U (Untrace) Command 

The U command is identical to the T command, except that intermediate program 
steps are not displayed. The untrace mode allows from 1 to 65535, (OFFFFH) steps to 
be executed in monitored mode and is used principally to retain control of an executing 1 
program while it reaches steady state conditions. All conditions of the T command 
apply to the U command. 

4.2.12 The X (Examine) Command 

The X command allows selective display and alteration of the current CPU state for 
the program under test. The X command takes the forms: {mm ^ 


X 

Xr 

where r is one of the 8080 CPU registers listed in the following table. 
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Table 4-3. CPU Registers 


Register 

Meaning 

Value 

C 

Carry flag 

(0/1) 

Z 

Zero flag 

(0/1) 

M 

Minus flag 

(0/1) 

E 

Even parity flag 

(0/1) 

I 

Interdigit carry 

(0/1) 

A 

Accumulator 

(0-FF) 

B 

BC register pair 

(0-FFFF) 

D 

DE register pair 

(0-FFFF) 

H 

HL register pair 

(0-FFFF) 

S 

Stack pointer 

(0-FFFF) 

P 

Program counter 

(0-FFFF) 


In the first case, the CPU register state is displayed in the format: 

CfZfMfEflf A = bb B = dddd D = dddd H = dddd S = dddd P = dddd inst 

where f is a 0 or 1 flag value, bb is a byte value, and dddd is a double-byte quantity 
corresponding to the register pair. The inst field contains the disassembled instruction, 
that occurs at the location addressed by the CPU state’s program counter. 

The second form allows display and optional alteration of register values, where r is 
one of the registers given above (C, Z, M, E, I, A, B, D, H, S, or P). In each case, the flag 
or register value is first displayed at the console. The DDT program then accepts input 
from the console. If a carriage return is typed, the flag or register value is not altered. If 
a value in the proper range is typed, the flag or register value is altered. You should note 
that BC, DE, and HL are displayed as register pairs. Thus, you must type the entire 
register pair when B, C, or the BC pair is altered. 


4.3 Implementation Notes 

The organization of DDT allows certain nonessential portions to be overlaid to gain 
a larger transient program area for debugging large programs. The DDT program 
consists of two parts: the DDT nucleus and the assembler/disassembler module. The 
DDT nucleus is loaded over the CCP and, although loaded with the DDT nucleus, the 
assembler/disassembler is overlayable unless used to assemble or disassemble. 
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In particular, the BDOS address at location 6H (address field of the JMP instruction 
at location 5H) is modified by DDT to address the base location of the DDT nucleus, mmm 
which, in turn, contains a JMP instruction to the BDOS. Thus, programs that use this 
address field to size memory see the logical end of memory at the base of the DDT 
nucleus rather than the base of the BDOS. 

The assembler/disassembler module resides directly below the DDT nucleus in the 
transient program area. If the A, L, T, or X commands are used during the debugging 
process, the DDT program again alters the address field at 6H to include this module, 
further reducing the logical end of memory. If a program loads beyond the beginning of 
the assembler/disassembler module, the A and L commands are lost (their use produces 
a ? in response) and the trace and display (T and X) commands list the inst field of the mm. 
display in hexadecimal, rather than as a decoded instruction. 


4.4 A Sample Program 


The following example shows an edit, assemble, and debug for a simple program 
that reads a set of data values and determines the largest value in the set. The largest 
value is taken from the vector and stored into LARGE at the termination of the 
program. 


A>ED SCAN. ASM 
* 7 / 


LOOP 

LOOP: 


NFOUND 


? 

I 


Create source program; 

“/” represents carriage return. 


ORG 

1-00H 

MV I 

B» LEN 

MV I 

C t 0 

LX I 

H» VECT 

MOV 

A» M 

SUB 

C 

JNC 

NFOUND 

NEW LARGEST 

VALUE t STORE 

MOV 

C» A 

I NX 

H 

DCR 

B 

JNZ 

LOOP 


END OF SCAN t STORE C/ 


5START OF TRANSIENT 
5AREA/ 

iLENGTH OF VECTOR TO SCAN/ 
5LARGER-RST VALUE SO FAR/ 

I BASE OF VECTOR/ 

I GET VALUE/ 

;LARGER VALUE IN C?/ 

I JUMP IF LARGER VALUE NOT 
5FOUND/ 

IT TO C/ 

5T0 NEXT ELEMENT/ 

5MORE TO SCAN?/ 

IFOR ANOTHER/ 




HPWP| 
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MOV 

A t C 

;get largest value/ 



STA 

LARGE / 


pin 

: / 

JMP 

0 

; REBOOT/ 


5/ 

TEST DATA 



pusj 

VECTs 

DB 

2 »0 >l\ »3 

>5>G,1 >5 


LEN 

EOU 

$-VECT 

ILENGTH 


LARGE: 

DS 

1 

5LARGEST VALUE ON EXIT 

r 

A "7 

END/ 




-L 

*BQP/ 




i 


ORG 

100H 

lSTART OF TRANSIENT AREA 

' 


MV I 

B >LEN 

1LENGTH OF VECTOR TO SCAN 



MV I 

C»0 

l LARGEST VALUE SO FAR 



LXI 

H »VECT 

;base of vector 


LOOP: 

MOV 

A »M 

? GET VALUE 



SUB 

C 

;LARGER VALUE IN C? 

ppsi 


JNC 

NFOUND 

IJUMP IF LARGER VALUE NOT 





;FOUND 


5 

NEW LARGEST 

VALUE t STORE IT TO C 



MOV 

Ct A 



NFOUND: 

INK 

H 

ito next element 



DCR 

B 

5MORE TO SCAN? 



JNZ 

LOOP 

IFOR ANOTHER 

pps 

5 

END OF SCAN 

» STORE C 




MOV 

A >C 

IGET LARGEST VALUE 



STA 

LARGE 



5 

JMP 

0 

1 REBOOT 


1 

TEST DATA 



faiPi 






VECT: 

DB 

2»<M>3 



LEN 

EQU 

$-VECT 

1 LENGTH 


LARGE: 

DS 

1 

1 LARGEST VALUE ON EXIT 



END 




*£/-• — 

End of edit 
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A >ASN SCAN/ Start Assembler 
CP/M ASSEMBLER - OER 1.0 


0122 

002H USE FACTOR 
END OF ASSEMBLY 


Assembly complete; lock at program listing 


to} TYPE SCAN* PRN/ 

Code address Source 

program 


01 


0RG 100H 

ISTART OF TRANSIENT AREA 

0100 0G08 


M0I B >LEN 

5 LENGTH OF OECTOR TO SCAN 

0102 0E00 Machine code 

MUI C#0 

1 LARGEST OALUE SO FAR 

0104 211901 


LXI H»VECT. 

;base OF OECTOR 

0107 7E 

LOOP: 

MOO A»M 

;get OALUE 

0108 91 


SUB C 

;LARGER OALUE IN C? 

0109 D20D01 


JNC NF0UND 

JJUMP IF LARGER OALUE NOT 


5 

;found 

NEW LARGEST VALUE» STORE IT TO C 

010C 4F 

010D 23 

NF0UND: 

MOO C,A 

INK H 

;to next element 

010E 05 


DCR B 

5MORE TO SCAN? 

01OF C20701 


JNZ LOOP 

5FOR ANOTHER 


i 

5 

END OF SCAN t 

STORE C 

0112 79 


MOO AtC 

;get largest oalue 

0113 322101 

0118 C30000 


STA LARGE 

JMP 0 

5REB00T 

Code—data listing 
truncated 

! 

! 

TEST DATA 


0119 0200040305 

VECTs 

DB 2»0»4»3»5 

>G 1 1 >5 

0008 = Value of 

LEN 

EQU $-0ECT 

iLENGTH 

0121 equate 

LARGE: 

DS 1 

1 LARGEST OALUE ON EXIT 

0122 


END 
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A>D£>r SCAN*HEX/ Start debugger using hex format machine code 


DDT MER 1,0 
NEXT PC 
0121 0000 

-Ay^Last load address 4- 1 


Next instruction 
to execute at 
PC = 0 

/ 

C0Z0M0E0I0 A=00 6=0000 D=0000 H=0000 S=0100 P=0000 OUT 7F 
-XP/f ^Examine registers before debug run 


pW 


P=0000 100 Change PC to 100 
-Ay Look at registers again 

C0Z0M0E0I0 A=00 B=0000 D=0000 H=0000 S=0100 P=0100 M01 B #08 

PC changed 




-L100/ 



0100 

MM I 

B»08 

0102 

MM I 

C #00 

0104 

LX I 

H#0119 

0107 

MOM 

AtM 

0108 

SUB 

C 

0109 

JNC 

010D 

0100 

MOM 

C#A 

010D 

I NX 

H 

010E 

DCR 

B 

010F 

JNZ 

0107 

0112 

MOM 

A *C 


Next instruction 
to execute at PC = 100 


Disassembled machine 
code at 100H 
(see source listing 
for comparison) 


-v 
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0113 

STA 

0121 

0116 

JMP 

0000 

0119 

STAX 

B 

011A 

NOP 


01 IB 

I NR 

B 

one 

INK 

B 

01 ID 

DCR 

B 

01 IE 

MM I 

B #01 

0120 

DCR 

B 

0121 

LX I 

D >2200 

0124 

LX I 

H >0200 

-A116/ 

Enter 

1 • 1 

in-line assem 


A little more machine 
code. Note that pro¬ 
gram ends at location 
116 with a JMP to 
0000. Remainder of 
listing is assembly of 
data. 


ever executed. 
0116 RST 7 


0117/ (Single carriage return stops assemble mode) 

-LI 13^ List code at 113H to check that RST 7 was properly inserted 


0113 

STA 

0121 

0116 

RST 

07 in place of JMP 

0117 

NOP 


0118 

NOP 


0119 

STAX 

B 

Oil A 

NOP 


01 IB 

I NR 

B 

one 

I NX 

B 


-/V/ Look at registers 

C0Z0M0E0I0 A=00 B=0000 D=0000 H=0000 S=0100 P=0100 MMI B>08 

-T/ 

Execute Program for one stop. Initial CPU state, before \ is executed 

C0Z0M0E0I0 A=00 B=0000 D=0000 H=0000 S=0100 P=0100 MMUB >08*0102 

Automatic breakpoint' 
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Trace one step again (note 08H in B) 

C0Z0M0E0I0 A=00 B=0800 D=0000 H=0000 S=0100 P=0102 MOI 


C >00*0104 


-v 

Trace again (Register C is cleared) 

C0Z0M0E0I0 A=00 B=0800 0=0000 H=0000 S=0100 P=0104 LXI H>0119*0107 


-^yTrace three steps 

lOZUMOEOIO A=00 B=0800 0=0000 H=0119 S=0100 
C0Z0M0E010 A=02 B=0800 0=0000 H=0119 S=0100 
C0Z0M0E0I1 A=02 B=0800 D=0000 H=0119 S=0100 


P=0107 MOO A >M 

P=0108 SUB C 

P=0108 JNC 0100*0100 


Display memory starting at 119H. Automatic breakpoint at 10DH 


0119 

0120 

02 

losj 

00 

11 

04 03 05 OB 
00 22 21 00 

op 

02 

7E 

EB 

Program data 
77 13 23 EB OB 


^Lower-case x_ 

B1 . W 7#T© 

0130 

02 

27 

01 03 03 29 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 ♦ ♦ ♦ ' m). 

0140 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 . 

0150 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 . 

01 GO 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 Data are displayed 

0170 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 in ASCII with a 

0180 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 in the position of 

0190 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 nongraphic. 

01A0 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 characters . 

01B0 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 . 

0100 

00 

00 

00 00 00 00 

00 

00 

00 

00 00 

00 

00 

00 

00 

00 . 


V / 

-•y 

Current CPU state 

C0Z0M0E0I1 A=02 B=0800 0=0000 H=0119 S=0100 P=010D INK H 

Trace 5 steps from current CPU state 
C0Z0M0E011 A=02 B=0800 0=0000 H=0119 S=0100 P=010D INK H 

C0Z0M0E011 A=02 B=0800 0=0000 H=011A 9=0100 P=010E OCR B 

C0Z0M0E011 A=02 B=0700 0=0000 H=011A S=0100 P=010F JNZ 0107 

C0Z0M0E011 A=02 B=0700 0=0000 H=011A S=0100 P=0107 MOO A >M 

C0Z0M0E0I1 A=00 B=0700 D=0000 H=011A S=0100 P=0108 SUB 0*0109 

U5 

Automatic breakpoint 
Trace without listing intermediate states 
C0Z1M0E111 A=00 B=0700 0=0000 H=011A S=0100 P=0109 JNC 0100*0108 
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^CPU state at end of U5 

C0Z0M0E1I1 A=04 B=06 00 D=0000 H=01IB S=0100 P=0108 SUB C 
-Gy Run program from current PC until completion (in real-time) 

*0116 breakpoint at 116H, caused by executing RST 7 in machine code. 


-,\y 

CPU state at end of program 

C0Z1M0E1I1 A=00 B 5 0000 0=0000 H=0121 S-0100 P=0116 RST 07 


-XP A 


/x 


Examine and change program counter 


P=0116 100y 


-V 

C0Z1M0E1II A=00 B=0000 D=0000 H=0121 S=0100 P=0100 MMI B.08 

-ny 








$0H 
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Trace 10 (hexadecimal) steps 
C0Z1M0E111 A=00 B=0800 D=00p«f H 
C0Z1M0E111 A=00 B=0000 DjfflOQ H 
C0Z1M0E111 A=00 B=080p/1)=00M 
C0Z1M0E111 A=00 B=Q81X) D=MX) H 
C0Z1M0E111 A=02^0800j>4000 H 
C0Z0M0E011 A<j§)B=0S@D=0000 H 
C0Z0M0E0I1 A=02 B=0800 D=0000 H 
C0Z0M0E0I1 A=02 B=0800 D=0000 H 
C0Z0M0E0I1 A=02 B=0700 D=0000 H 
C0Z0M0E0I1 A=02 B=0700 D=0000 H 
C0Z0M0E0I1 A=00 B=0700 D=0000 H 
C0Z1M0E1I1 A=00 B=0700 D=0000 H 
C0Z1M0E111 A=00 B=0700 D=0000 H 
C0Z1M0E1I1 A=00 B=0700 D=0000 H 
C0Z0M0E1I1 A=00 B=0800 D=0000 H 
C0Z0M0E1I1 A=00 B=0G00 D=0000 H 


First data element 

Current largest value 

Subtract for comparison C 


0Y?yi 

21 
0121 
0118 
0118 
=0113 
=0113 
=011A 
Oil A 
=011A 
011A 
Oil A 
Oil A 
01 IB 
01 IB 
01 IB 


S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 
S=0100 

s=0100 

S=0100 

S=0100 

S=0100 

S=0100 


P=0100 MOI 
P=0102 MOI 

p=oioa lx i 

P=0107 MOO 
P=0108 SUB 
P=0109 JNC 
P=010D INK 
P=010E DOR 
P=01OF JNZ 
P=0107 MOO 
P=0108 SUB 
P=0108 /JNC 
P=010D/INX 
P=010Ef DCR 
P=010JF JNZ 
P=01C v MOO 


-aios/ 

Insert a “hot patch’ 
the machine code 
0108 JC 10D to change the 
JNC to JC 

010C/ 


into 


Program should have moved the 
value from A into C since A>C. 
Since this code was not executed, 
it appears that the JNC should 
have been a JC instruction 


Stop DDT so that a version of 
- GO/ the patched program can be saved 

A >SAVE 1 SCAN* COM/ Program resides on first 
page, so save 1 page. 

A >DDT SCAN* COM/ 

^^Restart DDT with the save memory 
DDT 0ER 1.0 image to continue testing 

NEXT PC 
0200 0100 
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-LI00^ List some code 


0100 

M01 

B #08 


0102 

M01 

C #00 


0104 

LX I 

H #0119 


0107 

MOO 

A #M 


0108 

SUB 

C 


0103 

JC 

010D Previous patch is present in X.COM 


010C 

MOO 

C #A 


010D 

INK 

H 

010E 

DCR 

B 


01 OF 

JNZ 

0107 


0112 

MOO 

A #C 



-XP/ 

P -- () 1 (){ 

- TIC/ 

Trace to see how patched version operates /Data is moved from A to C 


C0Z0M0E0I0 

A=00 

B=0000 

D=0000 

H=0000 S=01#6 

P=0100 

MO I 

B #08 


C0Z0M0E0I0 

A=00 

B=0800 

D=0000 

H=0000 SdflOO 

P=0102 

MO I 

C #00 


C0Z0M0E0I0 

A=00 

B=0800 

D=0000 

H=0M/S=0100 

P=0104 

LX I 

H #0119 


C0Z0M0E0I0 

A=00 

B=0800 D=0000 

H=p*fl3 S=0100 

P=0107 

MOO 

A #M 

B "* 1 

C0Z0M0E0I0 

A<@ 

B=0800 

D=000C[/ 

-44=0119 S=0100 

P=0108 

SUB 

C 


C0Z0M0E0I1 

A=0T 

^=0800 

D=(hX50 

H=0119 S=0100 

P=0109 

JC 

010D 


C0Z0M0E0I1 

A=02 

B=b^00 

D^DOOO 

H=0119 S=0100 

P=010C 

MOO 

C#A 


C0Z0M0E0I1 

A=02 

B^jE^UZ} 

D=0000 

H=0119 S=0100 

P=010D 

I NX 

H 


C0Z0M0E0I1 

A=02 

B=0802 

D=0000 

H=011A S=0100 

P=010E 

DCR 

B 


C0Z0M0E0I1 

A=02 

B=0702 

D=0000 

H=011A S=0100 

P=010F 

JNZ 

0107 


C0Z0M0E0I1 

A=02 

B=0702 

D=0000 

H=011A S=0100 

P=0107 

MOO 

A >M 


C0Z0M0E0I1 

A=00 

B=0702 

D=0000 

H=011A S=0100 

P=0108 

SUB 

C 


C1Z0M1E0I0 

A=FE 

B=0702 

D=0000 

H=011A S=0100 

P=0103 

JC 

010D 


C1Z0M1E0I0 

A=FE 

B=0702 

D=0000 

H=011A S=0100 

P=010D 

I NX 

H 

C1Z0M1E0I0 

A=FE 

B=0702 

D=0000 

*H=01IB S=0100 

P=010E 

DCR 

B 


C1Z0M0E111 

‘V 

A=FE 

B=0G02 

D=0000 

H=01IB S=0100 P=010F JNZ 0107*0107 
Breakpoint after 16 steps' 


C1Z0M0E1I1 

A=FE 

B=0G02 

D=0000 

H=011B S=0100 

P=0107 

MOO 

A #M 


-GflOB/ Run from current PC and breakpoint at 108H 
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fmm 





*0108 




-v 

^Next data item 



C1Z0M0E1I1 A=04 B=0G02 D=0000 H=01IB 5=0100 P=0108 

SUB C 


-v 




Single step for a few cycles 



C1Z0M0E1I1 A=04 B=0602 D=0000 H=01IB S=0100 P=0108 

SUB 00109 


-v 







1 

C0Z0M0E0I1 A=02 B=0G02 0=0000 H=011B S=0100 P=0109 

JC 0100010C 


-v 




C0Z0M0E0I1 A=02 B=0G02 0=0000 H=011B S=0100 P=010C 

MOO C >A 


-G/ Run to completion 



*0115 




-v 




C0Z1M0E1I1 A=03 B=0003 0=0000 H=0121 S=0100 P=011G 

RST 07 


-S121/ 

Look at the value of “LARGE” 



0121 

03/ Wrong value! 



0122 

00/ 


f$Pi*l 

0123 

22/ 



0124 

21/ 







0125 

00/ 


1 

012G 

02/ 



0127 

7E/ _ End of the S command 


pm 
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-L100/ 




0100 

MO I 

B #08 


0102 

MO I 

C tOO 


0104 

LXI 

H#0119 


0107 

MOO 

A »M 


0108 

SUB 

C 


0109 

JC 

010D 


010C 

MOO 

C»A 

Mil 

010D 

I NX 

H 


010E 

DCR 

B 


010F 

JNZ 

0107 


0112 

MOO 

A »C 


■v 



► Review the code 

0113 

STA 

0121 


0116 

RST 

07 


0117 

NOP 



0118 

NOP 



0119 

STAX 

: b 


011A 

NOP 



01 IB 

I NR 

B 


one 

I NX 

B 


01 ID 

DCR 

B 


01 IE 

MO I 

B *01 


0120 

DCR 

B 


-7 




P=0116 

100 

Reset the PC 



-V 

Single step, and watch data values 

C0Z1M0E1I1 A=03 B=0003 0=0000 H=0121 S=0100 P=0100 MOI B.08*0102 

•v 

C0Z1M0E1I1 A=03 B=0803 D=0000 H=0121 S=0100 P=0102 M01 C.00*0104 

-V 

Count set^ ^Largest set 

C0Z1M0E111 A=03 B=0800 D=0000 H=0121 S=0100 P=0104 LXI H»0113*0107 

-V 
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^Base address of data set 

C0Z1M0E1I1 A=03 B=0800 D=0000 H=0119 S=0100 P=0107 MOM Ath*0108 

-y 

^-First data item brought to A 

C0Z1M0E1I1 A=02 B=0800 0=0000 H=0119 S=0100 P-0108 SUB 0*0109 


-V 


C0Z0M0EOI1 A=02 B=0800 D=0000 H=0119 S=0100 P=0109 JC 0100*0100 

-y 


C0Z0M0E0I1 A=02 B=0800 0=0000 H=0119 S=0100 P=010C MOO C.A*010D 

-y 

^First data item moved to C correctly 
C0Z0M0E0I1 A=02 B=0802 D=0000 H=0119 S=0100 P=010D INK H*010E 


-y 


C0Z0M0E0I1 A=02 B=0B02 D=0000 H=011A S=0100 P=010E DOR B*010F 

-y 


C0Z0M0E0I1 A=02 B=0702 0=0000 H=011A S=0100 P=010F JNZ 0107*0107 


C0Z0M0E0I1 A=02 B=0702 0=0000 H=011A S=0100 P=0107 MOO A,M*0108 

-y 

^Second data item brought to A 
C0Z0M0E0I1 A=00 B=0702 0=0000 H=011A S=0100 P=0108 SUB 0*0109 

-y 

^Subtract destroys data value that was loaded! 
C1Z0M1E0I0 A=FE B=0702 D=0000 H=011A S=0100 P=0109 JC 010D*010D 

-y 

C1Z0M1E0I0 A=FE B=0702 D=0000 H=011A S=0100 P=010D INX H*010E 
-LI 00/ 
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0100 

MU I 

B tOB 


0102 

MU I 

C >00 


0104 

LX I 

H >0118 


0107 

M0U 

A >M 


0108 

SUB 

C -This should have been a CMP so that register A 

___ 

0108 

JC 

010D would not be destroyed. 


010C 

M0U 

C >A 


010D 

I NX 

H 


010E 

DCR 

B 


01 OF 

JNZ 

0107 


0112 

-A108/ 

M0U 

A >C 



0108 CMP C / Hot patch at 108H changes SUB to CMP 


0109 


-GO/ Stop DDT for SAVE 
A >SA0E 1 SCAN.COM/ Save memory image 
teDDTSCAN.COM/ Restart DDT 


DDT UER DO 
NEXT PC 
0200 0100 


-XP/ 




P=0100 




- lug/ 




0116 

RST 

07™ 


0117 

NOP 



0118 

NOP 


Look at code to see if 

0113 

STAX 

B 

(long typeout aborted 

011A 

NOP 



-GfU6/ 

Run from 100H to completion 



it was properly loaded 
with rubout) 
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*0116 

-X 'Ey Look at carry (accidental typo) 

cy 

-Ay Look at CPU state 

C1Z1M0E111 A=06 B=0006 D=0000 H=0121 S=0100 P=011G RST 07 
-S121y Look at “large”—it appears to be correct. 

0121 06 / 

0122 00/ 

0123 22 

-Gey Stop DDT 

A >ED SCANiASMy Re-edit the source program, and make both changes 

*NSUB / 

*0LT / 



CTRL-Z 

SUB 

C 

I LARGER VALUE IN C? 



r 

*SSUBfZCMPtZ0LT / 

CMP 

D 

iLARGER VALUE IN C? 





JNC 

NF0UND 

1JUMP IF LARGER VALUE 

NOT 

FOUND 

■— 

tSNCtZtfZOLT / 

JC 

NF0UND 

5JUMP IF LARGER VALUE 

NOT 

FOUND 


*E/ 

Reassemble, selecting source from disk A 
A >ASM SCANiAAZf «- Hex to disk A 

Print to Z (selects no print file) 

CP/M ASSEMBLER UER 1.0 

0122 

002H USE FACTOR 
END OF ASSEMBLY 
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A >DDT SCAN*HEXf Rerun debugger to check changes 


DDT UER 1.0 
NEXT PC 

0121 0000 

-LI 16, 

/ 

0116 JMP 

0119 STAX 

011A NOP 
0116 INR 

-(rub out) 


0000 Check to ensure end is still at 116H 
B 

B 


- G100fll6y Go from beginning with breakpoint at end 

#0116 Breakpoint reached 
-D121j Look at “LARGE” 

^^^Correct value computed 

0121 @00 22 21 00 02 7E EB 77 13 23 EB 0B 78 B1 .. W 

0130 C2 27 01 C3 03 29 00 00 00 00 00 00 00 00 00 00 . 

0140 00 00 00 00 00 00 OO 00 OO 00 00 OO 00 00 00 00 . 

- (rubout) Aborts long typeout 

GCy Stop DDT, debug session complete. 


End of Section 4 
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CP/M 2 System Interface 


5.1 Introduction 

This chapter describes CP/M (release 2) system organization including the structure 
of memory and system entry points. This section provides the information you need to 
write programs that operate under CP/M and that use the peripheral and disk I/O 
facilities of the system. 

CP/M is logically divided into four parts, called the Basic Input/Output System 
(BIOS), the Basic Disk Operating System (BDOS), the Console Command Processor 
(CCP), and the Transient Program Area (TPA). The BIOS is a hardware-dependent 
module that defines the exact low level interface with a particular computer system that 
is necessary for peripheral device I/O. Although a standard BIOS is supplied by Digital 
Research, explicit instructions are provided for field reconfiguration of the BIOS to 
match nearly any hardware environment, see Section 6. 

The BIOS and BDOS are logically combined into a single module with a common 
entry point and referred to as the FDOS. The CCP is a distinct program that uses the 
FDOS to provide a human-oriented interface with the information that is cataloged on 
the back-up storage device. The TPA is an area of memory, not used by the FDOS and 
CCP, where various nonresident operating system commands and user programs are 
executed. The lower portion of memory is reserved for system information and 
is detailed in later sections. Memory organization of the CP/M system is shown in 
Figure 5-1. 
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HIGH 
MEMORY 
FBASE: 

CBASE: 

TBASE: 

BOOT: 

Figure 5-1. CP/M Memory Organization 


FDOS (BDOS+BIOS) 


CCP 


TP A 


SYSTEM PARAMETERS 










The exact memory addresses corresponding to BOOT, TBASE, CBASE, and FBASE 
vary from version to version and are described fully in Section 6. All standard CP/M 
versions assume BOOT = 0000H, which is the base of random access memory. The 
machine code found at location BOOT performs a system warm start, which loads and 
initializes the programs and variables necessary to return control to the CCP. Thus, 
transient programs need only jump to location BOOT to return control to CP/M at the 
command level. Further, the standard versions assume TBASE = BOOT -P0100H, 
which is normally location 0100H. The principal entry point to the FDOS is at location 
BOOT + 0005H (normally 0005H) where a jump to FBASE is found. The address field 
at BOOT + 0006H (normally 0006H) contains the value of FBASE and can be used to 
determine the size of available memory, assuming that the CCP is being overlaid by a 
transient program. mm ^. 
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|S§iSi 


|»PW 

ffiWl 




Transient programs are loaded into the TPA and executed as follows. The operator 
communicates with the CCP by typing command lines following each prompt. Each 
command line takes one of the following forms: 

command 
command filel 
command filel file2 

where command is either a built-in function, such as DIR or TYPE, or the name of a 
transient command or program. If the command is a built-in function of CP/M, it is 
executed immediately. Otherwise, the CCP searches the currently addressed disk for a 
file by the name 

c ommand♦COM 

If the file is found, it is assumed to be a memory image of a program that executes in 
the TPA and thus jmplicity originates at TBASE in memory. The CCP loads the COM 

file from the disk into memory starting at TBASE and can extend up to CBASE. 

) 

If the command is followed by one or two file specifications, the CCP prepares one 
or two File Control Block (FCB) names in the system parameter area. These optional 
FCBs are in the form necessary to access files through the FDOS and are described in 
Section 5.2. 

The transient program receives control from the CCP and begins execution, using the 
I/O facilities of the FDOS. The transient program is called from the CCP. Thus, it can 
simply return to the CCP upon completion of its processing, or can jump to BOOT to 
pass control back to CP/M. In the first case, the transient program must not use 
memory above CBASE, while in the latter case, memory up through FBASE-1 can be 
used. 

The transient program can use the CP/M I/O facilities to communicate with the 
operator’s console and peripheral devices, including the disk subsystem. The I/O system 
is accessed by passing a function number and an information address to CP/M through 
the FDOS entry point at BOOT + 0005H. In the case of a disk read, for example, the 
transient program sends the number corresponding to a disk read, along with the 
address of an FCB to the CP/M FDOS. The FDOS, in turn, performs the operation and 
returns with either a disk read completion indication or an error number indicating that 
the disk read was unsuccessful. 
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5.2 Operating System Call Conventions 

This section provides detailed information for performing direct operating system 
calls from user programs. Many of the functions listed below, however, are accessed 
more simply through the I/O macro library provided with the MAC macro assembler 
and listed in the Digital Research manual entitled, Programmer's Utilities Guide for the 
CP/M Family of Operating Systems. 


CP/M facilities that are available for access by transient programs fall into two 
general categories: simple device I/O and disk file I/O. The simple device operations are 


■ read a console character 

■ write a console character 

■ read a sequential character 

■ write a sequential character 

■ get or set I/O status 

■ print console buffer 

■ interrogate console ready 

The following FDOS operations perform disk I/O: 


■ disk system reset 

■ drive selection 

■ file creation 

■ file close 

■ directory search 

■ file delete 

■ file rename 

■ random or sequential read 

■ random or sequential write 

■ interrogate available disks 

■ interrogate selected disk 

■ set DMA address 

■ set/reset file indicators. 





As mentioned above, access to the FDOS functions is accomplished by passing a 
function number and information address through the primary point at location 
BOOT + 0005H. In general, the function number is passed in register C with the 
information address in the double byte pair DE. Single byte values are returned in 
register A, with double byte values returned in HL, a zero value is returned when the 
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function number is out of range. For reasons of compatibility, register A = L and 
register B = H upon return in all cases. Note that the register passing conventions of 
CP/M agree with those of the Intel PL/M systems programming language. CP/M func¬ 
tions and their numbers are listed below. 


0 System Reset 

1 Console Input 

2 Console Output 

3 Reader Input 

4 Punch Output 

5 List Output 

6 Direct Console I/O 

7 Get I/O Byte 

8 Set I/O Byte 

9 Print String 

10 Read Console Buffer 

11 Get Console Status 

12 Return Version Number 

13 Reset Disk System 

14 Select Disk 

15 Open File 

16 Close File 

17 Search for First 

18 Search for Next 


19 Delete File 

20 Read Sequential 

21 Write Sequential 

22 Make File 

23 Rename File 

24 Return Login Vector 

25 Return Current Disk 

26 Set DMA Address 

27 Get Addr(Alloc) 

28 Write Protect Disk 

29 Get R/O Vector 

30 Set File Attributes 

31 Get Addr(Disk Parms) 

32 Set/Get User Code 

33 Read Random 

34 Write Random 

35 Compute File Size 

36 Set Random Record 

37 Reset Drive 

40 Write Random with Zero Fill 


Functions 28 and 32 should be avoided in application programs to maintain upward 
compatibility with CP/M. 
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Upon entry to a transient program, the CCP leaves the stack pointer set to an 
eight-level stack area with the CCP return address pushed onto the stack, leaving seven 
levels before overflow occurs. Although this stack is usually not used by a transient 
program (most transients return to the CCP through a jump to location 0000H) it is 
large enough to make CP/M system calls because the FDOS switches to a local stack at 
system entry. For example, the assembly-language program segment below reads char¬ 
acters continuously until an asterisk is encountered, at which time control returns to 
the CCP, assuming a standard CP/M system with BOOT = 0000H. 


BDOS 

EQU 

0005H 

5STANDARD CP/M ENTRY 

CON IN 

EQU 

1 

ICONSOLE INPUT FUNCTION 

i 

ORG 

0100H 

iBASE OFTPA 

NEXTC: 

mi 

CtCONIN 

5 READ NEXT CHARACTER 


CALL 

BDOS 

5RETURN CHARACTER IN <A> 


CPI 


;END OF PROCESSING? 


JNZ 

NEXTC 

5L00P IF NOT 


RET 


5RETURN TO CCP 


END 




CP/M implements a named file structure on each disk, providing a logical organiza¬ 
tion that allows any particular file to contain any number of records from completely 
empty to the full capacity of the drive. Each drive is logically distinct with a disk 
directory and file data area. The disk filenames are in three parts: the drive select code, 
the filename (consisting of one to eight nonblank characters), and the filetype (consist¬ 
ing of zero to three nonblank characters). The filetype names the generic category of a 
particular file, while the filename distinguishes individual files in each category. The 
filetypes listed in Table 5-1 name a few generic categories that have been established, 
although they are somewhat arbitrary. 
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Table 5-1. CP/M Filetypes 


Filetype 

Meaning 

ASM 

Assembler Source 

PRN 

Printer Listing 

HEX 

Hex Machine Code 

BAS 

Basic Source File 

INT 

Intermediate Code 

COM 

Command File 

PLI 

PL/I Source File 

REL 

Relocatable Module 

TEX 

TEX Formatter Source 

BAK 

ED Source Backup 

SYM 

SID Symbol File 

$$$ 

Temporary File 


Source files are treated as a sequence of ASCII characters, where each line of the 
source file is followed by a carriage return, and line-feed sequence (ODH followed by 
OAH). Thus, one 128-byte CP/M record can contain several lines of source text. The 
end of an ASCII file is denoted by a CTRL-Z character (1AH) or a real end-of-file 
returned by the CP/M read operation. CTRL-Z characters embedded within machine 
code files (for example, COM files) are ignored and the end-of-file condition returned 
by C?/M is used to terminate read operations. 
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Files in CP/M can be thought of as a sequence of up to 65536 records of 128 bytes 
each, numbered from 0 through 65535, thus allowing a maximum of 8 megabytes per 
file. Note, however, that although the records may be considered logically contiguous, 
they may not be physically contiguous in the disk data area. Internally, all files are 
divided into 16K byte segments called logical extents, so that counters are easily 
maintained as 8-bit values. The division into extents is discussed in the paragraphs that 
follow: however, they are not particularly significant for the programmer, because each 
extent is automatically accessed in both sequential and random access modes. 

In the file operations starting with Function 15, DE usually addresses a FCB. Tran¬ 
sient programs often use the default FCB area reserved by CP/M at location 
BOOT + 005CH (normally 005CH) for simple file operations. The basic unit of file 
information is a 128-byte record used for all file operations. Thus, a default location for 
disk I/O is provided by CP/M at location BOOT + 0080H (normally 0080H) which is 
the initial default DMA address. See Function 26. 

All directory operations take place in a reserved area that does not affect write 
buffers as was the case in release 1, with the exception of Search First and Search Next, 
where compatibility is required. 

The FCB data area consists of a sequence of 33 bytes for sequential access and a 
series of 36 bytes in the case when the file is accessed randomly. The default FCB, 
normally located at 005CH, can be used for random access files, because the three bytes 
starting at BOOT + 007DH are available for this purpose. Figure 5-2 shows the FCB 
format with the following fields. 


DR 

0 

F2 

E3 

F8 

0 

T2 

T3 

EX 

SI 

S2 

RC 

DO 

□ 

DN 

CR 

R0 

R1 

R2 


00 01 02 ... 08 09 10 11 12 13 14 15 16 ... 31 32 33 34 35 

Figure 5-2. File Control Block Format 
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The following table lists and describes each of the fields in the File Control Block figure. 


Table 5-2. File Control Block Fields 


Field 

Definition 

dr 

drive code (0-16) 

0 = use default drive for file 

1 = auto disk select drive A, 

2 = auto disk select drive B, 


16 = auto disk select drive P. 

fl. . .f8 

contain the filename in ASCII upper-case, with high bit m 0 

tl,t2, t3 

contain the filetype in ASCII upper-case, with high bit = 0 tT, t2’, 
and t3’ denote the bit of these positions, 
tl’ = 1 = >Read-Only file, 
t2’ = 1 = >SYS file, no DIR list 

ex 

contains the current extent number, normally set to 00 by the user, 
but in range 0-31 during file I/O 

si 

reserved for internal system use 

s2 

reserved for internal system use, set to zero on call to OPEN, MAKE, 
SEARCH 

rc 

record count for extent ex; takes on values from 0-127 

dO. . .dn 

filled in by CP/M; reserved for system use 

cr 

current record to read or write in a sequential file operation; normal¬ 
ly set to zero by user 

rO, rl, r2 

optional random record number in the range 0-65535, with over¬ 
flow to r2, rO, rl constitute a 16-bit value with low byte rO, and high 
byte rl 
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Each file being accessed through CP/M must have a corresponding FCB, which 
provides the name and allocation information for all subsequent file operations. When 
accessing files, it is the programmer’s responsibility to fill the lower 16 bytes of the FCB 
and initialize the cr field. Normally, bytes 1 through 11 are set to the ASCII character 
values for the filename and filetype, while all other fields are zero. 

FCBs are stored in a directory area of the disk, and are brought into central memory 
before the programmer proceeds with file operations (see the OPEN and MAKE func¬ 
tions). The memory copy of the FCB is updated as file operations take place and later 
recorded permanently on disk at the termination of the file operation, (see the CLOSE 
command). 

The CCP constructs the first 16 bytes of two optional FCBs for a transient by 
scanning the remainder of the line following the transient name, denoted by file 1 and 
file2 in the prototype command line described above, with unspecified fields set to 
ASCII blanks. The first FCB is constructed at location BOOT + 005CH and can be used 
as is for subsequent file operations. The second FCB occupies the dO. . .dn portion of 
the first FCB and must be moved to another area of memory before use. If, for example, 
the following command line is typed: 

PROGNAME B : X ♦ Z 0 T Y.ZAP 

the file PROGNAME* CON is loaded into the TPA, and the default FCB at 
BOOT + 005CH is initialized to drive code 2, filename X, and filetype ZOT. The 
second drive code takes the default value 0, which is placed at BOOT-006CH, with 
the filename Y placed into location BOOT + 006DH and filetype ZAP located 8 bytes 
later at BOOT + 0075H. All remaining fields through cr are set to zero. Note again that 
it is the programmer’s responsibility to move this second filename and filetype to 
another area, usually a separate file control block, before opening the file that begins at 
BOOT -I- 005CH, because the open operation overwrites the second name and type. 

If no filenames are specified in the original command, the fields beginning at 
BOOT + 005DH and BOOT + 006DH contain blanks. In all cases, the CCP translates 
lower-case alphabetics to upper-case to be consistent with the CP/M file naming con¬ 
ventions. 
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As an added convenience, the default buffer area at location BOOT + OO 8 OH is 
initialized to the command line tail typed by the operator following the program name. 
The first position contains the number of characters, with the characters themselves 
following the character count. Given the above command line, the area beginning at 
BOOT + 0080H is initialized as follows: 

BOOT + 0080H: 

+ 00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +A +B +C +D +E 
E ° ‘B’ V ‘X’ V ‘Z’ ‘O’ T’ ° ‘Y’ V 4 Z' ‘A’ ‘P’ 

where the characters are translated to upper-case ASCII with uninitialized memory 
following the last valid character. Again, it is the responsibility of the programmer to 
extract the information from this buffer before any file operations are performed, 
unless the default DMA address is explicitly changed. 

Individual functions are described in detail in the pages that follow. 


FUNCTION 0: SYSTEM RESET 


Entry Parameters: 

Register C: 00H 


The System Reset function returns control to the CP/M operating system at the CCP 
level. The CCP reinitializes the disk subsystem by selecting and logging-in disk drive A. 
This function has exactly the same effect as a jump to location BOOT. 
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FUNCTION 1: CONSOLE INPUT 

Entry Parameter*: 


Register C: 

01H 

Returned Value: 


Register A: 

ASCII Character 


mrn^ 




The Console Input function reads the next console character to register A. Graphic mm \ 
characters, along with carriage return, line-feed, and back space (CTRL-H) are echoed 
to the console. Tab characters, CTRL-I, move the cursor to the next tab stop. A check is 
made for start/stop scroll, CTRL-S, and start/stop printer echo, CTRL-P. The FDOS 
does not return to the calling program until a character has been typed, thus suspending 
execution if a character is not ready. 


FUNCTION 2: CONSOLE OUTPUT 


Entry Parameters: 

Register C: 02H 
Register E: ASCII Character 


The ASCII character from register E is sent to the console device. As in Function 1, 
tabs are expanded and checks are made for start/stop scroll and printer echo. 
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FUNCTION 3: READER INPUT 

Entry Parameters: 


Register C: 

03H 

Returned Value: 


Register A: 

ASCII Character 


The Reader Input function reads the next character from the logical reader into 
register A. See the lOBYTE definition in Section 6. Control does not return until the 
character has been read. 


FUNCTION 4: PUNCH OUTPUT 

Entry Parameters: 


Register C: 

04H 

Register E: 

ASCII Character 


The Punch Output function sends the character from register E to the logical punch 
device. 
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FUNCTION 5: LIST OUTPUT 

Entry Parameters: 


Register C: 

05H 

Register E: 

ASCII Character 






The List Output function sends the ASCII character in register E to the logical listing 
device. 


FUNCTION 6 

DIRECT CONSOLE I/O 

Entry Parameters: 


Register C: 

06H 

Register E: 

OFFH (input) or 


char (output) 

Returned Value: 

char or status 

Register A: 





ftNKjj 


(sfi^ 


Direct Console I/O is supported under CP/M for those specialized applications where 
basic console input and output are required. Use of this function should, in general, be 
avoided since it bypasses all of the CP/M normal control character functions (for 
example, CTRL-S and CTRL-P). Programs that perform direct I/O through the BIOS 
under previous releases of CP/M, however, should be changed to use direct I/O under ■ 
BDOS so that they can be fully supported under future releases of MP/M and CP/M. 

Upon entry to Function 6, register E either contains hexadecimal FF, denoting a 
console input request, or an ASCII character. If the input value is FF, Function 6 returns 
A = 00 if no character is ready, otherwise A contains the next console input character. 

If the input value in E is not FF, Function 6 assumes that E contains a valid ASCII mm S 
character that is sent to the console. 

Function 6 must not be used in conjunction with other console I/O functions. f mm . 
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The Get I/O Byte function returns the current value of IOBYTE in register A. See 
Section 6 for IOBYTE definition. 




The Print String function sends the character string stored in memory at the location 
given by DE to the console device, until a $ is encountered in the string. Tabs are 
expanded as in Function 2, and checks are made for start/stop scroll and printer echo. 
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The Read Buffer function reads a line of edited console input into a buffer addressed 
by registers DE. Console input is terminated when either input buffer overflows or a 
carriage return or line-feed is typed. The Read Buffer takes the form: 


FUNCTION 10: 

READ CONSOLE BUFFER 

Entry Parameters: 

Register C: 
Registers DE: 

OAH 

Buffer Address 

Returned Value: 

Console Characters in Buffer 


DE: 

+ 0 

+ 1 

+ 2 

+ 3 

+ 4 

+ 5 

+ 6 

+ 7 +8 

mx 

nc 

cl 

c2 

c3 

c4 

c5 

c6 

c7 ... 


where mx is the maximum number of characters that the buffer will hold, 1 to 255, and f 
nc is the number of characters read (set by FDOS upon return) followed by the charac¬ 
ters read from the console. If nc < mx, then uninitialized positions follow the last 
character, denoted by ?? in the above figure. A number of control functions, summar 
ized in Table 5-3, are recognized during line editing. 




Table 5-3. Edit Control Characters 


Character 

Edit Control Function 

r u b / d e 1 

removes and echoes the last character 

CTRL-C 

reboots when at the beginning of line 

CTRL-E 

causes physical end of line 

CTRL-H 

backspaces one character position 

CTRL-J 

(line-feed) terminates input line 
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Table 5-3. (continued) 



The user should also note that certain functions that return the carriage to the leftmost 
position (for example, CTRL-X) do so only to the column position where the prompt 
ended. In earlier releases, the carriage returned to the extreme left margin. This conven¬ 
tion makes operator data input and line correction more legible. 



am The Console Status function checks to see if a character has been typed at the 
■ ~ console. If a character is ready, the value OFFH is returned in register A. Otherwise a 
00H value is returned. 
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FUNCTION 12: 

RETURN VERSION NUMBER 

Entry Parameter*: 


Register C: 

0CH 

Returned Value: 

Version Number 

Registers HL: 



Function 12 provides information that allows version independent programming. A 
two-byte value is returned, with H = 00 designating the CP/M release (H = 01 for 
MP/M) and L = 00 for all releases previous to 2.0. CP/M 2.0 returns a hexadecimal 20 
in register L, with subsequent version 2 releases in the hexadecimal range 21,22, 
through 2F. Using Function 12, for example, the user can write application programs 
that provide both sequential and random access functions. 


FUNCTION 13: RESET DISK SYSTEM 


Entry Parameters: 

Register C: 0DH 






The Reset Disk function is used to programmatically restore the file system to a reset 
state where all disks are set to Read-Write. See functions 28 and 29, only disk drive A is 
selected, and the default DMA address is reset to BOOT + 0080H. This function can be 
used, for example, by an application program that requires a disk change without a 
system reboot. 


Wiil^ 
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pm 


FUNCTION 14: SELECT DISK 

Entry Parameters: 


Register C: 

OEH 

Register E: 

Selected Disk 


The Select Disk function designates the disk drive named in register E as the default 
disk for subsequent file operations, with E = 0 for drive A, 1 for drive B, and so on 
through 15, corresponding to drive P in a full 16 drive system. The drive is placed in an 
on-line status, which activates its directory until the next cold start, warm start, or disk 
system reset operation. If the disk medium is changed while it is on-line, the drive 
automatically goes to a Read-Only status in a standard CP/M environment, see Func¬ 
tion 28. FCBs that specify drive code zero (dr = OOH) automatically reference the 
currently selected default drive. Drive code values between 1 and 16 ignore the selected 
default drive and directly reference drives A through P. 






FUNCTION 15: OPEN FILE 

Entry Parameters: 


Register C: 

OFH 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Directory Code 


The Open File operation is used to activate a file that currently exists in the disk 
f* 1 * directory for the currently active user number. The FDOS scans the referenced disk 
^ ' directory for a match in positions 1 through 14 of the FCB referenced by DE (byte si is 
automatically zeroed) where an ASCII question mark (3FH) matches any directory 
pw character in any of these positions. Normally, no question marks are included, and 
—> bytes ex and s2 of the FCB are zero. 
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If a directory element is matched, the relevant directory information is copied into 
bytes dO through dn of FCB, thus allowing access to the files through subsequent read 
and write operations. The user should note that an existing file must not be accessed 
until a successful open operation is completed. Upon return, the open function re¬ 
turns a directory code with the value 0 through 3 if the open was successful or OFFH 
(255 decimal) if the file cannot f)e found. If question marks occur in the FCB, the first 
matching FCB is activated. Note that the current record, (cr) must be zeroed by the 
program if the file is to be accessed sequentially from the first record. 


FUNCTION 16: CLOSE FILE 

Entry Parameters: 


Register C: 

10H 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Directory Code 




fM0$ 


The Close File function performs the inverse of the Open File function. Given that 
the FCB addressed by DE has been previously activated through an open or make 
function, the close function permanently records the new FCB in the reference disk ^*1 
directory see functions 15 and 22. Thsc FCB matching process for the close is identical 
to the open function. The directory code returned for a successful close operation is 0, 

1, 2, or 3, while a OFFH (255 decimal) is returned if the filename cannot be found in the titai \ 
directory. A file need not be closed if only read operations have taken place. If write 
operations have occurred, the close operation is necessary to record the new directory 
information permanently. *** 
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FUNCTION 17: SEARCH FOR FIRST 

Entry Parameters: 


Register C: 

11H 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Directory Code 


Search First scans the directory for a match with the file given by the FCB addressed 
by DE. The value 255 (hexadecimal FF) is returned if the file is not found; otherwise, 0, 
P*l, 2, or 3 is returned indicating the file is present. When the file is found, the current 
~DMA address is filled with the record containing the directory entry, and the relative 
starting position is A *32 (that is, rotate the A register left 5 bits, or ADD A five times). 
p^Although not normally required for application programs, the directory information 
-^can be extracted from the buffer at this position. 

ppn) An ASCII question mark (63 decimal, 3F hexadecimal) in any position from fl 
' —through ex matches the corresponding field of any directory entry on the default or 
auto-selected disk drive. If the dr field contains an ASCII question mark, the auto disk 
select function is disabled and the default disk is searched, with the search function 
I returning any matched entry, allocated or free, belonging to any user number. This 
latter function is not normally used by application programs, but it allows complete 
flexibility to scan all current directory values. If the dr field is not a question mark, the 
f^s2 byte is automatically zeroed. 


ppiPf 
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FUNCTION 18: SEARCH FOR NEXT 


Entry Parameters: 

Register C: 12H 

Returned Value: 

Register A: Directory Code 






The Search Next function is similar to the Search First function, except that the 
directory scan continues from the last matched entry. Similar to Function 17, Function 
18 returns the decimal value 255 in A when no more directory items match. 








FUNCTION 19: DELETE FILE 

Entry Parameters: 


Register C: 

13H 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Directory Code 


The Delete File function removes files that match the FCB addressed by DE. The 
filename and type may contain ambiguous references (that is, question marks in various 
positions), but the drive select code cannot be ambiguous, as in the Search and Search 
Next functions. 


Function 19 returns a decimal 255 if the referenced file or files cannot be found; 
otherwise, a value in the range 0 to 3 returned. 



i 
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FUNCTION 20: READ SEQUENTIAL 

Entry Parameters: 


Register C: 

14H 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Directory Code 


Given that the FCB addressed by DE has been activated through an Open or Make 
function, the Read Sequential function reads the next 128-byte record from the file into 
memory at the current DMA address. The record is read from position cr of the extent, 
and the cr field is automatically incremented to the next record position. If the cr field 
overflows, the next logical extent is automatically opened and the cr field is reset to zero 
in preparation for the next read operation. The value 00H is returned in the A register if 
the read operation was successful, while a nonzero value is returned if no data exist at 
the next record position (for example, end-of-file occurs). 
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FUNCTION 21: WRITE SEQUENTIAL 

Entry Parameters: 


Register C: 

15H 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Directory Code 


Given that the FCB addressed by DE has been activated through an Open or Make 
function, the Write Sequential function writes the 128-byte data record at the current 
DMA address to the file named by the FCB. The record is placed at position cr of the 
file, and the cr field is automatically incremented to the next record position. If the cr 
field overflows, the next logical extent is automatically opened and the cr field is reset to 
zero in preparation for the next write operation. Write operations can take place into 
an existing file, in which case, newly written records overlay those that already exist in 
the file. Register A = 00H upon return from a successful write operation, while a 
nonzero value indicates an unsuccessful write caused by a full disk. 


Gmt§ 






simf 
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FUNCTION 22: MAKE FILE 

Entry Parameters: 


Register C: 

16H 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Directory Code 


The Make File operation is similar to the Open File operation except that the FCB 
must name a file that does not exist in the currently referenced disk directory (that is, 
the one named explicitly by a nonzero dr code or the default disk if dr is zero). The 
FDOS creates thd file and initializes both the directory and main memory value to an 
empty file. The programmer must ensure that no duplicate filenames occur, and a 
preceding delete operation is sufficient if there is any possibility of duplication. Upon 
return, register A = 0, 1, 2, or 3 if the operation was successful and OFFH (255 
decimal) if no more directory space is available. The Make function has the side effect 
of activating the FCB and thus a subsequent open is not necessary. 


FUNCTION 23: RENAME FILE 

Entry Parameters: 


Register C: 

17H 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Directory Code 


The Rename function uses the FCB addressed by DE to change all occurrences of the 
file named in the first 16 bytes to the file named in the second 16 bytes. The drive code 
dr at postion 0 is used to select the drive, while the drive code for the new filename at 
position 16 of the FCB is assumed to be zero. Upon return, register A is set to a value 
between 0 and 3 if the rename was successful and OFFH (255 decimal) if the first 
filename could not be found in the directory scan. 
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FUNCTION 24: RETURN LOG-IN VECTOR 


Entry Parameters: 

Register C: 18H 

Returned Value: 

Registers HL: Log-in Vector 


The log-in vector value returned by CP/M is a 16-bit value in HL, where the least 
significant bit of L corresponds to the first drive A and the high-order bit of H corres¬ 
ponds to the sixteenth drive, labeled P. A 0 bit indicates that the drive is not on-line, 
while a 1 bit marks a drive that is actively on-line as a result of an explicit disk drive 
selection or an implicit drive select caused by a file operation that specified a nonzero dr 
field. The user should note that compatibility is maintained with earlier releases, be¬ 
cause registers A and L contain the same values upon return. 


FUNCTION 25: 

RETURN CURRENT DISK 

Entry Parameters: 


Register C: 

19H 

Returned Value: 


Register A: 

Current Disk 


Function 25 returns the currently selected default disk number in register A. The disk 
numbers range from 0 through 15 corresponding to drives A through P. 
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FUNCTION 26: SET DMA ADDRESS 


Entry Parameters: 

Register C: 1AH 
Registers DE: DMA Address 


DMA is an acronym for Direct Memory Address, which is often used in connection 
with disk controllers that directly access the memory of the mainframe computer to 
transfer data to and from the disk subsystem. Although many computer systems use 
non-DMA access (that is, the data is transferred through programmed I/O operations), 
the DMA addressjhas, in CP/M, come to mean the address at which the 128-byte data 
record resides befpre a disk write and after a disk read. Upon cold start, warm start, or 
disk system reset, ; the DMA address is automatically set to BOOT-I- 0080H. The Set 
DMA function can be used to change this default value to address another area of 
memory where the data records reside. Thus, the DMA address becomes the value 
specified by DE until it is changed by a subsequent Set DMA function, cold start, warm 
start, or disk system reset. 


FUNCTION 27: GET ADDR (ALLOC) 


Entry Parameters: 

Register C: 1BH 

Returned Value: 

Registers HL: ALLOC Address 


An allocation vector is maintained in main memory for each on-line disk drive. 
Various system programs use the information provided by the allocation vector to 
determine the amount of remaining storage (see the STAT program). Function 27 
returns the base address of the allocation vector for the currently selected disk drive. 
However, the allocation information might be invalid if the selected disk has been 
marked Read-Only. Although this function is not normally used by application pro¬ 
grams, additional details of the allocation vector are found in Section 6. 
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The Write Protect Disk function provides temporary write protection for the current¬ 
ly selected disk. Any attempt to write to the disk before the next cold or warm start 
operation produces the message: 


BDOS ERR on d:R/0 





Hf 


Function 29 returns a bit vector in register pair HL, which indicates drives that have 
the temporary Read-Only bit set. As in Function 24, the least significant bit corres¬ 
ponds to drive A, while the most significant bit corresponds to drive P. The R/O bit is 
set either by an explicit call to Function 28 or by the automatic software mechanisms 
within CP/M that detea changed disks. 

fliaUKT' ■? 


famm, 
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I RRRf 


r 

FUNCTION 30: SET FILE ATTRIBUTES 

pw 

Entry Parameters: 


Register C: 1EH 

Registers DE: FCB Address 




Returned Value: 

Register A: Directory Code 


p 


The Set File Attributes function allows programmatic manipulation of permanent 
indicators attached to files. In particular, the R/O and System attributes (tl ’ and t2’) 
can be set or reset. The DE pair addresses an unambiguous filename with the appropri¬ 
ate attributes set or reset. Function 30 searches for a match and changes the matched 
directory entry to contain the selected indicators. Indicators fl* through f4’ are not 
pw currently used, but may be useful for applications programs, since they are not involved 

— 4 in the matching process during file open and close operations. Indicators f5’ through f8’ 

and t3’ are reserved for future system expansion. 




The address of the BIOS resident disk parameter block is returned in HL as a result of 
this function call. This address can be used for either of two purposes. First, the disk 
parameter values can be extracted for display and space computation purposes, or 
transient programs can dynamically change the values of current disk parameters when 
the disk environment changes, if required. Normally, application programs will not 
require this facility. 
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FUNCTION 32: SET/GET USER CODE 

Entry Parameters: 


Register C: 

20H 

Register E: 

OFFH (get) or 

User Code (set) 

Returned Value: 


Register A: 

Current Code or 
(no value) 


fMf 






An application program can change or interrogate the currently active user number 
by calling Function 32. If register E = OFFH, the value of the current user number is 
returned in register A, where the value is in the range of 0 to 15. If register E is not 
OFFH, the current user number is changed to the value of E, modulo 16. 


FUNCTION 33: READ RANDOM 

Entry Parameters: 


Register C: 

21H 

Returned Value: 


Register A: 

Return Code 


Ml 


MEf 




The Read Random function is similar to the sequential file read operation of previous 
releases, except that the read operation takes place at a particular record number, 
selected by the 24-bit value constructed from the 3-byte field following the FCB (byte 
positions rO at 33, rl at 34, and r2 at 35). The user should note that the sequence of 24 
bits is stored with least significant byte first (rO), middle byte next (rl), and high byte 
last (r2). CP/M does not reference byte r2, except in computing the size of a file 
(Function 35). Byte r2 must be zero, however, since a nonzero value indicates overflow 
past the end of file. 
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Thus, the rO, rl byte pair is treated as a double-byte, or word value, that contains the 
record to read. This value ranges from 0 to 65535, providing access to any particular 
record of the 8-megabyte file. To process a file using random access, the base extent 
(extent 0) must first be opened. Although the base extent might or might not contain 
any allocated data, this ensures that the file is properly recorded in the directory and is 
visible in DIR requests. The selected record number is then stored in the random record 
field (rO, rl), and the BDOS is called to read the record. 

Upon return from the call, register A either contains an error code, as listed below, or 
the value 00, indicating the operation was successful. In the latter case, the current 
DMA address contains the randomly accessed record. Note that contrary to the se¬ 
quential read operation, the record number is not advanced. Thus, subsequent random 
read operations continue to read the same record. 

Upon each random read operation, the logical extent and current record values are 
automatically set. Thus, the file can be sequentially read or written, starting from the 
current randomly accessed position. However, note that, in this case, the last randomly 
read record will be reread as one switches from random mode to sequential read and 
the last record will be rewritten as one switches to a sequential write operation. The 
user can simply advance the random record position following each random read or 
write to obtain the effect of sequential I/O operation. 

Error codes returned in register A following a random read are listed below. 

01 r e a d i n sf u n written data 
0 2 (not re'tur n e d in r a n d o m m ode) 

03 cannot close current extent 
04 s e e K t o u rewritten e x t e n t 
05 (not ret urn e d in read mode) 

0G seek past physical end of disk 

Error codes 01 and 04 occur when a random read operation accesses a data block 
that has not been previously written or an extent that has not been created, which are 
equivalent conditions. Error code 03 does not normally occur under proper system 
operation. If it does, it can be cleared by simply rereading or reopening extent zero as 
long as the disk is not physically write protected. Error code 06 occurs whenever byte 
r2 is nonzero under the current 2.0 release. Normally, nonzero return codes can be 
treated as missing data, with zero return codes indicating operation complete. 
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FUNCTION 34: WRITE RANDOM 

Entry Parameters: 


Register C: 

22H 

Registers DE: 

FCB Address 

Returned Value: 


Register A: 

Return Code 


The Write Random operation is initiated similarly to the Read Random call, except 
that data is written to the disk from the current DMA address. Further, if the disk 
extent or data block that is the target of the write has not yet been allocated, the 
allocation is performed before the write operation continues. As in the Read Random 
operation, the random record number is not changed as a result of the write. The 
logical extent number and current record positions of the FCB are set to correspond to 
the random record that is being written. Again, sequential read or write operations can 
begin following a random write, with the notation that the currently addressed record 
is either read or rewritten again as the sequential operation begins. You can also simply 
advance the random record position following each write to get the effect of a sequen¬ 
tial write operation. Note that reading or writing the last record of an extent in random 
mode does not cause an automatic extent switch as it does in sequential mode. 


IfiMff 






(Suil 








The error codes returned by a random write are identical to the random read opera¬ 
tion with the addition of error code 05, which indicates that a new extent cannot be 
created as a result of directory overflow. 
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FUNCTION 35: COMPUTE FILE SIZE 


Entry Parameters: 

Register C: 23H 
Registers DE: FCB Address 

Returned Value: 

Random Record Field Set 


When computing the size of a file, the DE register pair addresses an FCB in random 
mode format (bytes rO, rl, and r2 are present). The FCB contains an unambiguous 
filename that is^used in the directory scan. Upon return, the random record bytes 
contain the virtual file size, which is, in effect, the record address of the record follow¬ 
ing the end of the file. Following a call to Function 35, if the high record byte r2 is 01, 
the file contains the maximum record count 65536. Otherwise, bytes rO and rl consti¬ 
tute a 16-bit value as before (rO is the least significant byte), which is the file size. 

Data can be appended to the end of an existing file by simply calling Function 35 to 
set the random record position to the end-of-file and then performing a sequence of 
random writes starting at the preset record address. 

The virtual size of a file corresponds to the physical size when the file is written 
sequentially. If the file was created in random mode and holes exist in the allocation, 
the file might contain fewer records than the size indicates. For example, if only the last 
record of an 8-megabyte file is written in random mode (that is, record number 65535), 
the virtual size is 65536 records, although only one block of data is actually allocated. 
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FUNCTION 36: SET RANDOM RECORD 


Entry Parameters: 

Register C: 24H 
Registers DE: FCB Address 

Returned Value: 

Random Record Field Set 


The Set Random Record function causes the BDOS automatically to produce the 
random record position from a file that has been read or written sequentially to a 
particular point. The function can be useful in two ways. 

First, it is often necessary initially to read and scan a sequential file to extract the 
positions of various key fields. As each key is encountered, Function 36 is called to 
compute the random record position for the data corresponding to this key. If the data 
unit size is 128 bytes, the resulting record position is placed into a table with the key for 
later retrieval. After scanning the entire file and tabulating the keys and their record 
numbers, the user can move instantly to a particular keyed record by performing a 
random read, using the corresponding random record number that was saved earlier. 
The scheme is easily generalized for variable record lengths, because the program need 
only store the buffer-relative byte position along with the key and record number to 
find the exact starting position of the keyed data at a later time. 

A second use of Function 36 occurs when switching from a sequential read or write 
over to random read or write. A file is sequentially accessed to a particular point in the 
file, Function 36 is called, which sets the record number, and subsequent random read 
and write operations continue from the selected point in the file. 
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FUNCTION 37: RESET DRIVE 

Entry Parameters: 


Register C: 

25 H 

Registers DE: 

Drive Vector 

Returned Value: 


Register A: 

00H 


The Reset Drive function allows resetting of specified drives. The passed parameter is 
a 16-bit vector of drives to be reset; the least significant bit is drive A:. 

To maintain compatibility with MP/M, CP/M returns a zero value. 



FUNCTION 40: WRITE RANDOM WITH ZERO FILL 


Entry Parameters: 


Register C: 28H 


Registers DE: FCB Address 


Returned Value: 


Register A: Return Code 


The Write With Zero Fill operation is similar to Function 34, with the exception that 
a previously unallocated block is filled with zeros before the data is written. 
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5.3 A Sample File-to-File Copy Program 

The following program provides a relatively simple example of file operations. The .^*1 
program source file is created as COPY.ASM using the CP/M ED program and then 
assembled using ASM or MAC, resulting in a HEX file. The LOAD program is used to 
produce a COPY.COM file that executes directly under the CCP. The program begins 
by setting the stack pointer to a local area and proceeds to move the second name from 
the default area at 006CH to a 33-byte File Control Block called DFCB. The DFCB is 
then prepared for file operations by clearing the current record field. At this point, the fs^ 
source and destination FCBs are ready for processing, because the SFCB at 005CH is 
properly set up by the CCP upon entry to the COPY program. That is, the first name is 
placed into the default FCB, with the proper fields zeroed, including the current record 
field at 007CH. The program continues by opening the source file, deleting any existing 
destination file, and creating the destination file. If all this is successful, the program 
loops at the label COPY until each record is read from the source file and placed into 
the destination file. Upon completion of the data transfer, the destination file is closed 
and the program returns to the CCP command level by jumping to BOOT. 


sample file-to-file copy program 
at the ccp level* the command 
copy a:x«y b:iuv 






copies the file named x.y from drive 
a to a file named u»v« on drive b« 


0000 = 

boot 

equ OOOOh 

isystem reboot 

0005 = 

bdos 

equ 0005h 

?bdos entry point 

005c = 

fcbl 

equ 005c h 

5first file name 

005c = 

sfcb 

equ fcbl 

isource fcb 

OOGc = 

f cb2 

equ OOGch 

Ssecond file name 

0080 = 

dbuff 

equ 0080h 

^default buffer 

0100 = 

tpa 

eqij OlOOh 

ibetfinninsf of tpa 

0009 = 

? 

printf 

equ 9 

Sprint buffer func# 

OOOf = 

openf 

equ 15 

5open file func# 

0010 = 

closef 

equ 16 

?close file func# 

0013 = 

deletef 

equ 19 

idelete file func# 

001 a = 

readf 

equ 20 

^sequential read 

0015 = 

writef 

equ 21 

isequential write 


fast 


mm 


§B»j 

mm 
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|PRW 







00 IB = 

makef 

e^u 

nn 

5 Make file func# 

jfPPSf 

0100 

? 

or* 

tpa 

5be3irmin3 of tpa 


0100 311b02 


lxi 

sp *stack 

? 1ocal stack 

ppij 


t 

5 

Move 

second file name to dfcb 


0103 OelO 


mu i 

c >16 

5half an fcb 


0105 HGcOO 


lxi 

d > f c b 2 

5source of Move 


0108 21daOl 


lxi 

h tdfcb 

^destination fcb 

1" 

010b la 

iiifcb: 

Id ax 

d 

Isource fcb 


010c 13 


inx 

d 

5 ready next 


OlOd 77 


MOV 

m >a 

5dest fcb 

ppfif 

OlOe 23 


inx 

h 

1 ready next 


01Of Od 


dcr 

c 

5count 16* * *0 


0110 clObOl 


Jnz 

Mf cb 

?1oop 1G tiMes 

jP®f 


5 






5 

name 

has been 

reMovedt zero cr 


0113 af 


xra 

a 

5a = 00h 

jlffBl! 

0114 32faOl 


sta 

dfcbcr 

Icurrent rec = 0 



? 

5 

source and destination fcb's ready 


0117 115c00 

! 

lxi 

d tsfcb 

Isource file 


011a cd6901 


call 

open 

terror if 255 

ji«p*r 

Olid 118701 


lxi 

d »nofile 

5 ready Message 

0120 3c 


in 

a 

5255 becomes 0 


0121 ccGlOl 


cz 

finis 

5done if no file 

JiP^I 


i 

5 

source file open* prep destination 

— 

0124 lldaOl 


lxi 

d tdfcb 

5 destination 


0127 cd7301 


call 

delete 

JreMOve if present 

jiiirtM 

012a lidaO1 

i 

lxi 

d tdfcb 

5 destination 


012d cdB201 


call 

Make 

5create the file 

IP*! 

0130 119801 


lxi 

d tnodir 

5 ready Message 

0133 3c 


inr 

a 

5255 becoMes 0 


0134 ccGlOl 


cz 

finis 

5done if no dir space 

pppw 


t 

5 

source file open# dest file open 



5 

copy 

until end 

of file on source 
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(■wsi 


0137 

115c00 

copy: 

lxi 

d >sfcb 

i source 


013a 

cd7801 


call 

read 

?read next record 


013d 

hi 


ora 

a 

5end of file? 


013e 

c25101 


jnz 

eof ile 

IsKip write if so 




i 

i 

not 

end of file 

t write the record 

(S§il| 

0141 

lid a01 


lix 

d»dfcb 

5 destination 


0144 

cd7d01 


call 

write 

iwrite record 


0147 

11a901 


lxi 

d >space 

i ready message 

S:*f^ 

014a 

b7 


ora 

a 

500 if write ok 


014b 

C4G101 


cnz 

finis 

5end if so 


014 e 

c33701 

j 

jlllP 

copy 

iloop until eof 

s 



eof ile: 

5 end 

of file# close destination 


0151 

lldaOl 


lxi 

d»dfcb 

idestination 


0154 

cdGeOl 


call 

close 

5255 if error 


0157 

21bbOl 


lxi 

h »wrprot 

iready message 


015a 

3c 


in r 

a 

5255 becomes 00 


015b 

ccGlOl 


cz 

finis 

ishouldn't happen 

mm 



j 

5 

copy 

operation 

complete# end 


015 e 

llccOl 


lxi 

d ^normal 

5 ready message 

iSi^ 



j 

finis 

iwrite message 

$iuen by de t reboot 


01G1 

0e09 


mu i 

c *printf 


mmn 

01G3 

cdOSOO 


call 

bdos 

iwrite message 


01GG 

c30000 


jwp 

boot 

5 reboot system 




! 

5 

system interface subroutines 

SsUf 



! 

(all 

return directly from bdos) 


01G9 

OeOf 

? 

open: 

mui 

c >openf 



01Gb 

c30500 


drop 

bdos 



OlGe 

OelO 

close: 

mui 

c *closef 



0170 

c30500 


Jiiip 

bdos 



0173 

Oe 13 

delete 

mu i 

c >deletef 



0175 

c30500 


JlllP 

bdos 
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0178 

Oelfl 

read: 

urn 

c i readf 

017a 

c30500 


jmp 

bdos 

017 d 

0el5 

j 

write: 

urn 

c >writef 

017 f 

c30500 


Jmp 

bdos 

0182 

OelG 

make: 

mo i 

c »makef 

00 

c30500 


jmp 

bdos 



i 

console messages 

0187 

GeGfZOf 

nofile: 

db 

Tio source file*' 

0198 

GeGf209 

nodir: 

db 

Tio directory space*' 

01a9 

Gf7574f 

space: 

db 

'out of dat space*' 

01 bb 

7772G95 

wrprot: 

db 

'write protected?*' 

Olcc 

G3Gf700 

no rmal: 

db 

'copy complete*' 



* 

i 

data 

areas 

01 da 


dfeb: 

ds 

33 ^destination feb 

01 fa 


dfeber 

equ 

dfcb+32 icurrent record 

01 fb 


» 

ds 

32 ; 16 1e m e1 stack 



stack: 



021b 



end 



N®te that there are several simplifications in this particular program. First, there are 
no checks for invalid filenames that could contain ambiguous references. This situation 
could be detected by scanning the 32-byte default area starting at location 005CH for 
ASCII question marks. A check should also be made to ensure that the filenames have 
been included (check locations 005DH and 006DH for nonblank ASCII characters). 
Finally, a check should be made to ensure that the source and destination filenames are 
different. An improvement in speed could be obtained by buffering more data on each 
read operation. One could, for example, determine the size of memory by fetching 
FBASE from location 0006H and using the entire remaining portion of memory for a 
data buffer. In this case, the programmer simply resets the DMA address to the next 
successive 128-byte area before each read. Upon writing to the destination file, the 
DMA address is reset to the beginning of the buffer and incremented by 128 bytes to 
the end as each record is transferred to the destination file. 
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5.4 A Sample File Dump Utility 

The following file dump program is slightly more complex than the simple copy 
program given in the previous section. The dump program reads an input file, specified 
in the CCP command line, and displays the content of each record in hexadecimal 
format at the console. Note that the dump program saves the CCP’s stack upon entry, 
resets the stack to a local area, and restores the CCP’s stack before returning directly to 
the CCP. Thus, the dump program does not perform and warm start at the end of 


processing. 





Kir 


IDUMP program 

reads input file and displays 


0100 

hex data 

i 

or3 

lOOh 



0005 = 

bd05 

e«m 

0005h = 

$bdos entry point 


0001 = 

cons 

e=m 

1 

5read console 

ISw#} 

0002 = 

typef 

esu 

n 

5type function 


0009 = 

printf 

epu 

9 

Ibuffer print entry 


000 b = 

brKf 

epu 

11 

IbreaK Key function 

SsH 





5(true if char 


000f = 

operif 

equ 

15 

ifile open 


0014 = 

readf 

e*ui 

20 

5read function 

iHIj 

005 c = 

j 

f cb 

e*Hi 

5c h 

Ifile control block 

iaddress 


0080 = 

buff 

esu 

80 h 

linput disk buffer 

Iaddress 



! 

5 

non 

Graphic 

characters 


000d = 

cr 

e<ui 

Odh 

1 carriage return 


000a = 

If 

5 

esu 

Oah 

lline feed 



5 

file 

control 

block definitions 


005c = 

fcbdn 

equ 

fcb+0 

IdisK name 


005 d = 

fcbfn 

epu 

fcb+1 

Ifile name 

famil 

00G5 = 

fcbft 

epi.i 

fcb+9 

IdisK file type (3 
Icharacters) 


0088 = 

fcbrl 

equ 

fcb+12 

Ifile 7 s current reel 

1number 


00Gb = 

fcbrc 

esu 

fcb+15 

Ifile's record count (0 to 






1128)128) 
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p 

007 c = 

fcbcr' 


007 d = 

f c b i n 

i 

r 

0100 210000 

0103 39 

i 

jP»I 

0104 221502 

i 

i 

jiMI 

0107 315702 

i 

i 


010a cdclOl 

OlOd feff 


ppspH 

OlOf c21b01 

5 


0112 11f301 

0115 c d 3 c 01 

5 

! 


0118 c35101 

5 

openok 

pRBf 

011b 3e80 



Olid 321302 


C 

0120 210000 

i 

i 

Sloop: 


0123 e5 

0124 cda201 

0127 el 



0138 da5101 



012b 47 


pP? 


i 

i 


012c 7d 


ppj 




equ fcb+32 

icur rent (next) record 

epu fcb+33 

inumber (0 

ifcb length 

set up stack 

lxi h >0 

dad SP 

entry stack pointer in hi from the ccp 

shld oldsp 

set sp to local 

stack area (restored at 

finis) 

lxi sp tstktop 

read and print 

successive buffers 

call setup 

5set up input file 

cpi 255 

5255 if file not present 

Jnz openok 

5skip if open is ok 

file not there » 

sine error message and 

return 

lxi d>opnmss 

call err 
jfnp finis 

ito return 

5open operation 

ok» set buffer index to 

5 end 

hi ui a»B0h 

sta ibp 

5set buffer pointer to BOh 

hi contains next address to print 

lxi h>0 

5start with 0000 


push h 

5 save 

line 

position 

call Snb 




CL 

O 

CL 

5recall line position 

jc finis 

icarry 

set 

by Snb if end 


if ile 



mov b»a 




print hex 

values 



check for 

line fold 




mov a*l 
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012d eGOf 
OlZf c24401 


0132 cd7201 


0135 cd5901 

0138 Of 
0139 da5101 

013c 7c 
013d cd8f01 
0140 7d 
0141 cdSfOl 

0144 23 
0145 3e20 
0147 cdGSOl 
014a 78 
014b cdSfOl 
014e c32301 


0151 cd7201 
0154 2a1502 
0157 f9 


0158 c9 


0159 e5d5c5 
015c OeOb 


no nu in 


f i n i s 


ani Ofh i check low 4 bits 

jnz nonurn 

print line number 

call crlf 

check for break key 
call break 

accum 1sb = 1 if character ready 


rrc 


5into carry 

Jc 

finis 

5don't print any more 

MOV 

a *h 


call 

phex 


MOV 

a t\ 


call 

phex 


inx 

h 

5 to next line number 

mv i 

a i'' 


call 

pchar 


mov 

a »b 


call 

phex 


jmp 

Sloop 



end of dump» return to cco 

(note that a jmp to OOOOh reboots) 

call crif 

lhId oldsp 

sphl 

stack pointer contains ccp's stack 
location 

ret 5to the ccp 


! subroutines 

5 

break: 5check break key (actually any key will 

5 do) 

push h! push d! push b» environment 

5 saved 

mvi c tb rkf 


mm 










mm 
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pm 



015e 

cdOSOO 


call 

bdos 


0161 

cldlel 


POP 1 

D! pop d! pop h5 environment 

j«PI 

0164 

c9 


restored 

ret 

n 

0165 

e5d5c5 

j 

pchar: 

Sprint a character 

push h! push d! push bi saved 


0168 

0e02 


mvi 

c> t'/pef 


016a 

5f 


mow 

e >a 

016b 

cdOSOO 


call 

bdos 


016 e 

cldlel 


POP 

b! pop d! pop hi restored 

p 1 

0171 

c9 

! 

crlf 

ret 



0172 

3e0d 


wvi 

a >cr 

mm 

0174 

cd6501 


call 

pchar 

f 

0177 

3e0a 


wvi 

a»If 


0179 

cd6501 


call 

pchar 


017c 

c9 


ret 



) 




pn i b: 

Sprint nibble in re$ a 

I" M: v '\ 

017d e60f 


ani ofh ilow 4 bits 


017f feOa 


cpi 10 


0181 d28901 


jnc p10 

pm 


5 

less than or equal to 9 

— 

0184 c630 


adi 'O' 


0186 c38b01 


jmp prn 



! 

Greater or equal to 10 

‘ ~ 

0189 c637 

5 

p 10: 

adi 'a' - 10 


018b cd6501 

p rn: 

call pchar 

018e c9 


ret 



5 

phex 

iprint hex char in re$ a 


018f f5 


pushpsw 


0190 Of 


rrc 


0191 Of 


rrc 


0192 Of 


rrc 

‘ - 

0193 Of 


rrc 


0194 c d7d01 


call pnib iprint nibb 
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0197 fl 
0198 c d7d01 
019b c9 

5 

»rr: 

5 

019c 0e09 

019 e cdOSOO 
Olal c9 

5 

5 

snb: 

01a2 3a1302 
01a5 feBO 
01a7 cZt«301 


01aa cdceOl 
01 ad b7 
01 ae cat«301 

i 

Olbl 37 
Olt-2 c9 

I 

SO: 

01b3 5f 
Olbfl 1600 

01bS 3c 
01b7 321302 

5 

5 

01ba 218000 
01bd 19 

? 

01 be 7e 

5 

01 bf b7 
01cO c9 
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finif 

POP P5W 

call pnip 

p 0 ^ uut 

Sprint error message 
d#e addresses messaSe ending with 
mvi CfPrintf 5print buffer 
5 function 

call bdos 
ret 




nut 


5 Set next byte 
Ida ibp 
cpi 80h 
Jnz SO 

read another buffer 






call disKr 

ora a Izero ualue if read ok 

Jz SO 5for another byte 

end of data> return with carry set for eof 

stc 

ret 


USif 


?read the byte at buff+res a 
mov e>a 5Is byte of buffer index 

mMi d»0 5double precision 

!index to de 

inr a 5in d e x=in d e x+1 

sta ibp 5 back to memory 

pointer is incremented 
save the current file address 
lxi htbuff 
dad d 

absolute character address is in hi 
mom a »ffl 

byte is in the accumulator 

ora a 5reset carry bit 

ret 






SSURf 
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5.4 A Sample File Dump Utility 




setup: 

iset lip file 




! 

open the file for input 


Old af 


xra a 

izero to accum 


01c2 327c00 


sta feber 

lelear current record 


01 c5 115c00 

i 

lxi d»fcb 


l _ 

01cB OeOf 


mui c»openf 



01 ca cdOSOO 


call bdos 




i 

255 in accum if 

open error 

r 

0led c9 


ret 




! 

disKr: 

5read disk file 

record 


Olce e5d5c5 


push h! push d! 

push b 


01dl 115c00 


lxi dffeb 



01 da Oeia 


m ui c>readf 



01dB cdOSOO 


call bdos 


— 

01d9 cldlel 


POP b! POP d! POP h 


01dc cS 


ret 


jipw 


i 

fixed message area 


01 dd msuco 

si Sri on: 

db 'file dump 

version 2*0$' 


01f3 OdOaaeO 

opnmsS: 

db cr»lf»'no 

input file present on 




disk*' 




5 

variable area 



0213 

i b p : 

ds 2 

5input buffer pointer 

c 

0215 

oldsp: 

ds 2 

I entry sp value from ccp 



j 

I 

stack area 


pps? 

0217 

! 

ds sa 

Preserve 32 level stack 

'■—- 


stktop: 




0257 


end 



m DIGITAL RESEARCH 


5-45 




5.5 Sample Random Access Program 


CP/M Operating System Manual 


5.5 A Sample Random Access Program 

This section concludes with an extensive example of random access operation. The 
program listed below performs the simple function of reading or writing random 
records upon command from the terminal. When a program has been created, assem¬ 
bled, and placed into a file labeled RANDOM ♦ COM , the CCP level command 

RANDOM X ♦ D A T 

starts the test program. The program looks for a file by the name X ♦ DAT and, if found, 
proceeds to prompt the console for input. If not found, the file is created before the 
prompt is given. Each prompt takes the form 

next command? 

and is followed by operator input, followed by a carriage return. The input commands 
take the form 

nWnRQ 

where n is an integer value in the range 0 to 65535, and W, R, and Q are simple 
command characters corresponding to random write, random read, and quit proces¬ 
sing, respectively. If the W command is issued, the RANDOM program issues the 
prompt 

type data: 

The operator then responds by typing up to 127 characters, followed by a carriage 
return. RANDOM then writes the character string into the X ♦ DAT file at record n. If 
the R command is issued, RANDOM reads record number n and displays the string 
value at the console, If the Q command is issued, the X ♦ DAT file is closed, and the 
program returns to the CCP. In the interest of brevity, the only error message is 

error# try a * ain ♦ 

The program begins with an initialization section where the input file is opened or 
created, followed by a continuous loop at the label ready where the individual com¬ 
mands are interpreted. The DFBC at 005CH and the default buffer at 0080H are used 
in all disk operations. The utility subroutines then follow, which contain the principal 
input line processor, called readc. This particular program shows the elements of 
random access processing, and can be used as the basis for further program develop¬ 
ment. 
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Sample Random Access Program for CP/M 2.0 


0100 


ors 

lOOh 

5base of tpa 

0000 = 

reboot 

equ 

0000 h 

5system reboot 

0005 = 

b d o s 

equ 

0005 h 

5bdos entry point 

0001 = 

i 

coninp 

equ 

1 

Jconsole input function 

0002 = 

conout 

equ 


1 console output function 

0009 = 

pstrinS 

equ 

9 

Sprint strinS until 

000 a = 

rstrinS 

equ 

10 

5read console buffer 

000 c = 

version 

equ 

12 

5return version number 

000 f = 

openf 

equ 

15 

ifile open function 

0010 = 

closef 

equ 

16 

Sclose function 

0016 = 

makef 

equ 

9? 

5make file function 

0021 = 

readr 

equ 

33 

1 read random 

0022 = 

write r 

equ 

34 

iwrite random 

005 c = 

? 

fcb 

equ 

005 c h 

;default file control 





y block 

007d = 

ran rec 

equ 

fcb+33 

5random record position 

007f = 

ranovf 

equ 

fcb+35 

ihish order (overflow) 





5 b y t e 

0080 = 

« 

buff 

equ 

0080h 

5 buffer address 

000d = 

? 

cr 

equ 

Odh 

IcarriaSe return 

000 a = 

If 

equ 

Oah 

51ine feed 





Load SP, Set-Up File for Random Access 

0100 31bcOO 

lxi 

sp *stack 


I versior 

i 2.0 

0103 OeOc 

mvi 

c »version 

0105 cdOSOO 

call 

bdos 

0108 fe20 

cpi 

20h 5version 2.0 or better? 

010a d21600 

Jnc 

versok 


5 bad version# message and So bacK 
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010d 

111bOO 

1 x i 

d >hadue r 


0110 

cddaOO 

call 

print 


0113 

c30000 

jiiip 

reboot 




uersok: 





i correct uersion for random access 


01 IB 

OeOf 

mui 

c»openf 5o p en default fcb 


0118 

115c00 

lxi 

d f f c t< 


out. 

cd 0500 

call 

t'd 0 5 

ms$ 

01 le 

3c 

in r 

a ierr 255 becomes zero 


01 If 

c23700 

Jnz 

ready 




i cannot 

open file* so create it 

m^ 

0122 

OelG 

m u i 

c >makef 


0124 

115c00 

lxi 

d »fcb 


0127 

cd0500 

call 

bdos 


012a 

3c 

in r 

a Ierr 255 becomes zero 


012b 

c23700 

jnz 

ready 




1 





5 cannot 

create file* directory full 


012 e 

113a00 

lxi 

d >nospace 


0131 

cddaOO 

call 

print 

(HUP 

0134 

c30000 

jfflP 

reboot ibacK to ccp 



Loop Back to Ready After Each Command 






ready: 




; file 

is ready for processing 

0137 

cdeSOO 

call 

readcom Sread next command 

013a 

227d00 

shld 

ranrec 5store input record* 

013d 

217f00 

lxi 

h»ranovf 

0140 

3G00 

mui 

m»0 iclear hi$h byte if 

0142 

f e51 

cpi 

/ 0 / ?suit? 

0144 

c25G00 

? jnz 

nots 



? suit 

processing) close file 

0147 

OelO 

mui 

c iclosef 

■Cs 

CO 

115c00 

lxi 

d »fcb 

014c 

cdOSOO 

call 

bdos 
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oiaf 

3c 

in r 

a 

lerr 255 becomes 0 

0150 

cab900 

jz 

error 

lerror message t retry 

0153 

c30000 

Jmp 

reboot 

Iback to ccp 


ppm 


pUBf 


pPW 


End of Quit Command, Process Write 
nots: 

I not the suit command* random write? 


0156 

fe57 

cpi 

'M' 


0158 

c28900 

jnz 

nolw 




i 

5 this 

is a random 

write > fill buffer i 

015b 

llfldOO 

lxi 

d »datmsa 


015e 

cddaOO 

call 

print 

Idata prompt 

0161 

0e7f 

moi 

c .127 

I up to 127 characte 

0163 

218000 

lxi 

h tbuff 

5 destination 



rloop: Iread 

next character to buff 

0166 

c5 

push 

b 

Isaue counter 

0167 

e5 

push 

h 

Inext destination 

0168 

cdc200 

call 

$etchr 

^character to a 

016b 

el 

POP 

h 

1 restore counter 

016c 

cl 

POP 

b 

irestore next to fi 

016 d 

feOd 

cpi 

cr 

5end of line? 

016f 

ca7800 

Jz 

erloop 




I not end* store character 

0172 

77 

mou 

m t a 


0173 

23 

inx 

h 

5next to fill 

0174 

Od 

dcr 

c 

5counter ^oes down 

0175 

c26600 

jnz 

rloop 

5end of buffer? 



erloop: 





1 end of read loop 

t store 00 

0178 

3600 

mui 

m *0 




i 

5 write 

the record 

to selected record i 

017a 

0e22 

mui 

c >writer 


017c 

115c00 

lxi 

d»fcb 


017c 

cdOSOO 

call 

bdos 


0182 

b7 

ora 

a 

lerror code zero? 

0183 

c2b900 

jnz 

error 

imessaae if not 

0186 

C33700 

jmp 

read/ 

Ifor another record 


cr 
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End of Write Command, Process Read 


notw: 

i not a write command* read record? 


0189 

fe52 

cpi 

'R' 


018b 

c2b900 

Jnz 

erro r 

isKip if not 



5 

5 read 

random record 

018 e 

0 e 21 

m u i 

c * read r 


0190 

115c00 

lxi 

d *fcb 


0193 

cdOSOO 

call 

b d 0 5 


0198 

t>7 

ora 

a 

5 return code 00? 

0197 

c2b900 

jnz 

error 




i read 

was successful* write to console 

019a 

cdcfOO 

cal 1 

c rlf 

inew line 

019d 

0e80 

III Ml 

c *128 

imax 128 characters 

019 f 

218000 

lxi 

h * buff 

5next to Set 



wIoop: 



01 a2 

7e 

111 0 u 

a fin 

inext character 

01 a3 

23 

inx 

h 

inext to Set 

Qlafl 

eG7f 

an i 

7fh 

imask parity 

01 aG 

ca3700 

JZ 

ready 

ifor another command 





;if oo 

01a9 

c5 

push 

b 

isaue counter 

01 aa 

e5 

push 

h 

isaue next to Set 

01 at. 

feZO 

cpi 

'' 

iSraphic? 

01 ad 

dflc800 

cnc 

putchr 

isKip output if not 

01 bO 

el 

POP 

h 


01 bl 

cl 

POP 

b 


01 bZ 

Od 

dcr 

c 

icount=count-l 

01 b 3 

cZaZOO 

jnz 

wloop 


01 bG 

c33700 

j in p 

ready 




End of Read Command, All Errors End Up Here 


error: 


01 b 9 

115900 

lxi 

d >errmsS 

01 be 

cddaOO 

call 

print 

01 bf 

c33700 

jmp 

ready 


J 
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pmv 


Utility Subroutines for Console I/O 


j®SIB 


01 c2 OeOl 
01 c4 cdOSOO 
01 c7 c9 


01c8 0e02 
01ca 5f 
01cb cd0500 
01ce c9 


01cf 3e0d 
01dl cdc800 
01d4 3e0a 
01dB cdc800 
01d9 c9 


P" 01 da d5 
01 db cdcfOO 
01de dl 

fpw 01 df 0e09 
-— 01 e0 cdOSOO 

01e4 c9 

|i»^ 

01e5 116b00 
01 e8 cddaOO 
01 eb OeOa 
Oled 117a00 
pw 01 f0 cdOSOO 

01f3 210000 
01 f 6 117c00 




pwi 

rwi 



$etch r: 

I read next console character to a 
myi c>coninp 

call bdos 
ret 


putchr: 

Jwrite character from a to console 
mvi ciconout 


mov 

e >a 

^character to sen 

call 

ret 

bdos 

Jsend character 


crlf: 


Jsend 

carriage 

return line feed 

mvi 

a ic r 

Icarriatfe return 

call 

putchr 


mvi 

a ilf 

Jline feed 

call 

putchr 


ret 




print: 


5 print 

the buffer addressed 

bv de i 

push 

d 


call 

crlf 


POP 

d 5new line 


mvi 

c »pstrinS 


call 

ret 

bdos Sprint the 

string 


re adcom: 


5 read 

the next command line to the 

lxi 

d >prompt 


call 

print 

5 command? 

mvi 

c > rst rins 


lxi 

d iconbuf 


call 

bdos 

5 read command 1 in 

command line is 

presenti scan it 

lxi 

h >0 

5 start with 0000 

lxi 

d iconi in 

!command line 
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01 f9 la 

readc: Idax 

d 

Inext command 
^character 

Olfa 13 

inx 

d 

5to next command 




^position 

Olfb t<7 

ora 

a 

5cannot be end of 

5 command 

Olfc c8 

rz 




5 not zerof numeric? 

01fd dG30 

sui 

'O' 


Olff feOa 

cpi 

10 

5carry if numeric 

0201 d21300 

jnc 

endrd 



5 add-in 

next ditfit 


0204 29 

dad 

h 

5*2 

0205 4d 

mov 

C tl 


0206 44 

MOV 

b»h 

?be = value * 2 

0207 29 

dad 

h 

;*4 

0208 29 

dad 

h 

;*8 

0209 09 

dad 

b 

;#2 + *8 = *10 

020a 85 

add 

1 

5*disit 

020b Gf 

mov 

1 #a 


020c d2f900 

jnc 

readc 

!for another char 

020f24 

inr 

h 

5 overflow 

0210 c3f900 

jfflp 

readc 

5for another char 


endrd: 




5 end of 

read t restore value in a 

0213 cG30 

adi 

'O' 

?command 

0215 feGl 

cpi 

'a' 

itrarislate case? 

0217 d8 

rc 




5 lower 

caset mask 

lower case bits 

0218 eG5f 

ani 

101$llllb 


021a c9 

ret 






String Data Area for Console Messages 




badver: 


021b 

536f79 

db 

nospace: 

'sorry* you need cp/m version 2$ 

023a 

4e6f29 

db 

datms*: 

'no directory space$' 
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024d 547970 

db 


errms$: 

0259 457272 

db 


prompt: 

026b 4eG570 

db 


5.5 Sample Random Access Program 

'type data: $' 

'error > try a4ain«$' 

'next command? $' 


Fixed and Variable Data Area 


027a 21 

co rib nf : 

db 

conlen 

51en*th of console buffer 

027b 

consiz: 

ds 

1 

5resulting size after read 

027c 

conlin: 

ds 

32 

5length 32 buffer 

0021 = 

conlen 

equ 

$-consiz 


029c 

5 

ds 

32 

516 level stack 


stack: 




02b c 


end 




Major improvements could be made to this particular program to enhance its opera¬ 
tion. In fact, with some work, this program could evolve into a simple data base 
management system. One could, for example, assume a standard record size of 128 
bytes, consisting to arbitrary fields within the record. A program, called GETKEY, 
could be developed that first reads a sequential file and extracts a specific field defined 
by the operator. For example, the command 

GETKEY NAMES ♦ DAT LASTNAME 10 20 

would cause GETKEY to read the data base file NAMES*DAT and extract the LAST- 
NAME field from each record, starting in position 10 and ending at character 20. 
GETKEY builds a table in memory consisting of each particular LASTNAME field, 
along with its 16-bit record number location within the file. The GETKEY program 
then sorts this list and writes a new file, called LASTNAME ♦ KEY, which is an 
alphabetical list of LASTNAME fields with their corresponding record numbers. This 
list is called an inverted index in information retrieval parlance. 

If the programmer were to rename the program shown above as QUERY and modify 
it so that it reads a sorted key file into memory, the command line might appear as 

QUERY NAMES ♦ DAT LASTNAME ♦ KEY 
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Instead of reading a number, the QUERY program reads an alphanumeric string that is 
a particular key to find in the NAMES ♦ DAT data base. Because the LASTNAME ♦ KEY 
list is sorted, one can find a particular entry rapidly by performing a binary search, 
similar to looking up a name in the telephone book. Starting at both ends of the list, one 
examines the entry halfway in between and, if not matched, splits either the upper half 
or the lower half for the next search. You will quickly reach the item you are looking 
for and find the corresponding record number. You should fetch and display this record 
at the console, just as was done in the program shown above. 


With some more work, you can allow a fixed grouping size that differs from the 
128-byte record shown above. This is accomplished by keeping track of the record 
number and the byte offset within the record. Knowing the group size, you randomly 
access the record containing the proper group, offset to the beginning of the group 
within the record read sequentially until the group size has been exhausted. 





Finally, you can improve QUERY considerably by allowing boolean expressions, 
which compute the set of records that satisfy several relationships, such as a LAST- 
NAME between HARDY and LAUREL and an AGE lower than 45. Display all the 
records that fit this description. Finally, if your lists are getting too big to fit into n 
memory, randomly access key files from the disk as well. 


5.6 System Function Summary 





Function 


Function 

Input 

Output 


Number 


Name 




mm 

Decimal 

0 

Hex 

0 

System Reset 

C = 

00H 

none 


1 

1 

Console Input 

C = 

01H 

A = ASCII char 


r> 


Console Output 

E = 

char 

none 

IWSFJ 

3 

3 

Reader Input 



A = ASCII char 


4 

4 

Punch Output 

E = 

char 

none 


5 

5 

List Output 

E = 

char 

none 

f#Wf| 

G 

G 

Direct Console I/O 

C = 

OGH 

A = char or status 




E = 

OFFH 

(input) or (no value) 






OFEH 

(status) or 

'1 





char 

(output) 


7 

7 

Get I/O Byte 

none 

A = I/O byte 







Value 
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8 

8 

Set I/O Byte 

E = I/O Byte 

none 

0 

9 

Print String 

DE = Buffer Address 

none 

10 

A 

Read Console Buffer 

DE = Buffer 

Console 

Characters 

in Buffer 

11 

B 

Get Console Status 

none 

A = 00/non zero 

12 

C 

Return Mere ion Number 

none 

HL: Version 

Number 

13 

D 

Reset Disk System 

none 

none 

14 

E 

Select Disk 

E = Disk Number 

none 

15 

F 

Open File 

DE = FCB Address 

FF if not found 

1G 

10 

Close File 

DE = FCB Address 

FF if not found 

17 

11 

Search For First 

DE = FCB Address 

A = Directory 

Code 

18 

12 

Search For Next 

none 

A = Directory 

Code 

19 

13 

Delete File 

DE = FCB Address 

A = none 

20 

14 

Read Sequential 

DE = FCB Address 

A = Error Code 

21 

15 

Write Sequential 

DE = FCB Address 

A = Error Code 

22 

IS 

Make File 

DE = FCB Address 

A = FF if no Dll 

Space 

23 

17 

Rename File 

DE = FCB Address 

A = FF in not 

found 

24 

16 

Return Lo^in Mector 

none 

HL = Lo4in 
Oector* 

25 

19 

Return Current Disk 

none 

A = Current Dis 

Number 

28 

1A 

Set DMA Address 

DE = DMA Address 

none 

•7 “7 

IB 

Get ADDR (ALLOC) 

none 

HL = ALLOC 

Address* 

28 

1C 

Write Protect Disk 

none 

none 

29 

ID 

Get Re ad/only Oector 

none 

HL = R/0 

Oector Value* 

30 

IE 

Set File Attributes 

DE = FCB Address 

A = none 

31 

IF 

Get ADDR (Disk Farms) 

none 

HL = DPB 

Address 

32 

20 

Set/Get User Code 

E = OFFH for Get 

E = 00 to OFH for Set 

User Number 

33 

21 

Read Random 

DE = FCB Address 

A = Error Code 

34 

•7 J ? 

Write Random 

DE = FCB Address 

A = Error Code 

35 

23 

Compute File Size 

DE = FCB Address 

rO t r 1 1 r2 

36 

24 

Set Random Record 

DE = FCB Address 

rO * rl t r2 
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37 

25 

Reset Drive 

DE = Drive Oector 

A = 0 

38 

26 

Access Drive 

not supported 


39 

27 

Free Drive 

not supported 


40 

28 

Write Random with Fill 

DE = FCB 

A = Error Code 


*Note that A = L, and B = H upon return. 


End of Section 5 
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Section 6 

CP/M 2 Alteration 


fTr’^spj 


6.1 Introduction 


The standard CP/M system assumes operation on an Intel MDS-800 microcomputer 
development system, but is designed so you can alter a specific set of subroutines that 
define the hardware operating environment. 


' Although standard CP/M 2 is configured for single-density floppy disks, field- 

alteration features allow adaptation to a wide variety of disk subsystems from single¬ 
drive minidisks to high-capacity, hard disk systems. To simplify the following adapta- 
P*** tion process, it is assumed that CP/M 2 is first configured for single-density floppy disks 
where minimal editing and debugging tools are available. If an earlier version of CP/M 
is available, the customizing process is eased considerably. In this latter case, you might 
want to review the system generation process and skip to later sections that discuss 
system alteration for nonstandard disk systems. 


|psi 


To achieve device independence, CP/M is separated into three distinct modules: 






■ BIOS is the Basic I/O System, which is environment dependent. 

■ BDOS is the Basic Disk Operating System, which is not dependent upon the 
hardware configuration. 

■ CCP is the Console Command Processor, which uses the BDOS. 

Of these modules, only the BIOS is dependent upon the particular hardware. You 
can patch the distribution version of CP/M to provide a new BIOS that provides a 
customized interface between the remaining CP/M modules and the hardware system. 
This document provides a step-by-step procedure for patching a new BIOS into CP/M. 


All disk-dependent portions of CP/M 2 are placed into a BIOS, a resident disk 
parameter block, which is either hand coded or produced automatically using the disk 
definition macro library provided with CP/M 2. The end user need only specify the 
maximum number of active disks, the starting and ending sector numbers, the data 
allocation size, the maximum extent of the logical disk, directory size information, and 
reserved track values. The macros use this information to generate the appropriate 
tables and table references for use during CP/M 2 operation. Deblocking information is 
pp, provided, which aids in assembly or disassembly of sector sizes that are multiples of the 
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fundamental 128-byte data unit, and the system alteration manual includes general 
purpose subroutines that use the deblocking information to take advantage of larger 
sector sizes. Use of these subroutines, together with the table-drive data access algo¬ 
rithms, makes CP/M 2 a universal data management system. 

File expansion is achieved by providing up to 512 logical file extents, where each 
logical extent contains 16K bytes of data. CP/M 2 is structured, however, so that as 
much as 128K bytes of data are addressed by a single physical extent, corresponding to 
a single directory entry, maintaining compatibility with previous versions while taking 
advantage of directory space. 

If CP/M is being tailored to a computer system for the first time, the new BIOS m 
requires some simple software development and testing. The standard BIOS is listed in 
Appendix A and can be used as a model for the customized package. A skeletal version 
of the BIOS given in Appendix B can serve as the basis for a modified BIOS. 

In addition to the BIOS, you must write a simple memory loader, called GETSYS, 
which brings the operating system into memory. To patch the new BIOS into CP/M, 
you must write the reverse of GETSYS, called PUTSYS, which places an altered version 
of CP/M back onto the disk. PUTSYS can be derived from GETSYS by changing the 
disk read commands into disk write commands. Sample skeletal GETSYS and PUTSYS 
programs are described in Section 6.4 and listed in Appendix C. 

To make the CP/M system load automatically, you must also supply a cold start 
loader, similar to the one provided with CP/M, listed in Appendixes A and D. A skeletal 
form of a cold start loader is given in Appendix E, which serves as a model for the 
loader. 
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6.2 First-level System Regeneration 

The procedure to patch the CP/M system is given below. Address references in each 
step are shown with H denoting the hexadecimal radix, and are given for a 20K CP/M 
system. For larger CP/M systems, a bias is added to each address that is shown with a 
+ b following it, where b is equal to the memory size-20K. Values for b in various 
standard memory sizes are listed in Table 6-1. 


Table 6-1. Standard Memory Size Values 


Memory Size 

Value 

24K: 

b = 24K - 

20K = 4K = 1000H 

32K: 

b = 32K - 

20K = 12K = 3000H 

40K: 

b = 40K - 

20K = 20K = 5000H 

48 K: 

b = 48K - 

20K = 28K = 7000H 

56K: 

b = 56K - 

20K = 36K = 9000H 

62K: 

b = 62K - 

20K = 42K = A800H 

64K: 

b = 64K - 

20K = 44 K = B000H 


Note that the standard distribution version of CP/M is set for operation within a 20K 
CP/M system. Therefore, you must first bring up the 20K CP/M system, then configure 
it for actual memory size (see Section 6.3). 

Follow these steps to patch your CP/M system: 

1. Read Section 6.4 and write a GETSYS program that reads the first two tracks 
of a disk into memory. The program from the disk must be loaded starting at 
location 3380H. GETSYS is coded to start at location 100H (base of the TPA) 
as shown in Appendix C. 

2. Test the GETSYS program by reading a blank disk into memory, and check to 
see that the data has been read properly and that the disk has not been altered 
in any way by the GETSYS program. 
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3. Run the GETSYS program using an initialized CP/M disk to see if GETSYS 
loads CP/M starting at 3380H (the operating system actually starts 128 bytes 
later at 3400H). 

4. Read Section 6.4 and write the PUTSYS program. This writes memory start¬ 
ing at 3380H back onto the first two tracks of the disk. The PUTSYS program 
should be located at 200H, as shown in Appendix C. 

5. Test the PUTSYS program using a blank, uninitialized disk by writing a 
portion of memory to the first two tracks; clear memory and read it back 
using GETSYS. Test PUTSYS completely, because this program will be used 
to alter CP/M on disk. 

6. Study Sections 6.5, 6.6, and 6.7 along with the distribution version of the 
BIOS given in Appendix A and write a simple version that performs a similar 
function for the customized environment. Use the program given in Appendix 
B as a model. Call this new BIOS by name CBIOS (customized BIOS). Imple¬ 
ment only the primitive disk operations on a single drive and simple console 
input/output functions in this phase. 

7. Test CBIOS completely to ensure that it properly performs console character 
I/O and disk reads and writes. Be careful to ensure that no disk write opera¬ 
tions occur during read operations and check that the proper track and sectors 
are addressed on all reads and writes. Failure to make these checks might 
cause destruction of the initialized CP/M system after it is patched. 

8. Referring to Table 6-3 in Section 6.5, note that the BIOS is placed between 
locations 4A00H and 4FFFH. Read the CP/M system using GETSYS and 
replace the BIOS segment by the CBIOS developed in step 6 and tested in step 
7. This replacement is done in memory. 

9. Use PUTSYS to place the patched memory image of CP/M onto the first two 
tracks of a blank disk for testing. 

10. Use GETSYS to bring the copied memory image from the test disk back into 
memory at 3380H and check to ensure that it has loaded back properly (clear 
memory, if possible, before the load). Upon successful load, branch to the cold 
start code at location 4A00H. The cold start routine initializes page zero, then 
jumps to the CCP at location 3400H, which calls the BDOS, which calls the 
CBIOS. The CCP asks the CBIOS to read sixteen sectors on track 2, and 
CP/M types A>, the system prompt. 

If difficulties are encountered, use whatever debug facilities are available to 
trace and breakpoint the CBIOS. 
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11. Upon completion of step 10, CP/M has prompted the console for a command 
input. To test the disk write operation, type 

S A 0 E 1 '•(♦COM 

All commands must be followed by a carriage return. CP/M responds with 
another prompt after several disk accesses: 

A > 

If it does not, debug the disk write functions and retry. 

12. Test the directory command by typing 
DIR 

CP/M responds with 
A: X COM 

13. Test the erase command by typing 
ERA X♦C0M 

CP/M responds with the A prompt. This is now an operational system that 
only requires a bootstrap loader to function completely. 

14. Write a bootstrap loader that is similar to GETSYS and place it on track 0, 
sector 1, using PUTSYS (again using the test disk, not the distribution disk). 
See Sections 6.5 and 6.8 for more information on the bootstrap operation. 

15. Retest the new test disk with the bootstrap loader installed by executing steps 
11, 12, and 13. Upon completion of these tests, type a CTRL-C. The system 
executes a warm start, which reboots the system, and types the A prompt. 

16. At this point, there is probably a good version of the customized CP/M system 
on the test disk. Use GETSYS to load CP/M from the test disk. Remove the 
test disk, place the distribution disk, or a legal copy, into the drive, and use 
PUTSYS to replace the distribution version with the customized version. Do 
not make this replacement if you are unsure of the patch because this step 
destroys the system that was obtained from Digital Research. 

17. Load the modified CP/M system and test it by typing 
DIR 

CP/M responds with a list of files that are provided on the initialized disk. The 
file DDT.COM is the memory image for the debugger. Note that from now 
on, you must always reboot the CP/M system (CTRL-C is sufficient) when the 
disk is removed and replaced by another disk, unless the new disk is to be 
Read-Only. 
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18. Load and test the debugger by typing 
DDT 

See Section 4 for operating procedures. 

19. Before making further CBIOS modifications, practice using the editor (see 
Section 2), and assembler (see Section 3). Recode and test the GETSYS, PUT- mm [ 
SYS, and CBIOS programs using ED, ASM, and DDT. Code and test a COPY 
program that does a sector-to-sector copy from one disk to another to obtain 
back-up copies of the original disk. Read the CP/M Licensing Agreement 
specifying legal responsibilities when copying the CP/M system. Place the 
following copyright notice: 


Copyright (c) t 1983 
Digital Research 

on each copy that is made with the COPY program. 

20. Modify the CBIOS to include the extra functions for punches, readers, and 
sign-on messages, and add the facilities for additional disk drives, if desired. 
These changes can be made with the GETSYS and PUTSYS programs or by 
referring to the regeneration process in Section 6.3. 


You should now have a good copy of the customized CP/M system. Although the 
CBIOS portion of CP/M belongs to the user, the modified version cannot be legally l * Wi ! 
copied. 


It should be noted that the system remains file-compatible with all other CP/M 
systems (assuming media compatibility) which allows transfer of nonproprietary soft¬ 
ware between CP/M users. 


6.3 Second-level System Generation 

Once the system is running, the next step is to configure CP/M for the desired ■*] 
memory size. Usually, a memory image is first produced with the MOVCPM program 
(system relocator) and then placed into a named disk file. The disk file can then be 
loaded, examined, patched, and replaced using the debugger and the system generation mm* 
program (refer to Section 1). 

The CBIOS and BOOT are modified using ED and assembled using ASM, producing 
files called CBIOS ♦ HEX and BOOT ♦HEX, which contain the code for CBIOS and 
BOOT in Intel hex format. 


IftKj 
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To get the memory image of CP/M into the TPA configured for the desired memory 
size, type the command: 

MOVCPM xx* 

where xx is the memory size in decimal K bytes, for example, 32 for 32K. The response 
is as follows: 

CONSTRUCTING xxK CP/M VERS 2*0 
READY FOR "SYSGEN" OR 
"SAVE 34 CPMxx.COM" 

An image of CP/M in the TPA is configured for the requested memory size. The 
memory image is at location 0900H through 227FH, that is, the BOOT is at 0900H, 
the CCP is at 980H, the BDOS starts at 1180H, and the BIOS is at 1F80H. Note that 
the memory image has the standard MDS-800 BIOS and BOOT on it. It is now 
necessary to save the memory image in a file so that you can patch the CBIOS and 
CBOOT into it: 

SAVE34CPMxx.COM 

The memory image created by the MOVCPM program is offset by a negative bias so 
that it loads into the free area of the TPA, and thus does not interfere with the 
operation of CP/M in higher memory. This memory image can be subsequently loaded 
under DDT and examined or changed in preparation for a new generation of the 
system. DDT is loaded with the memory image by typing: 

DDT CPMxx.COM Loads DDT, then reads the CP/M image. 

DDT should respond with the following: 

NEXT PC 
2 3 0 0 0 1 0 0 

(The DDT prompt) 

You can then give the display and disassembly commands to examine portions of the 
memory image between 900H and 227FH. Note, however, that to find any particular 
address within the memory image, you must apply the negative bias to the CP/M 
address to find the actual address. Track 00, sector 01, is loaded to location 900H (the 
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user should find the cold start loader at 900H to 97FH); track 00, sector 02, is loaded 
into 980H (this is the base of the CCP); and so on through the entire CP/M system load. 
In a 20K system, for example, the CCP resides at the CP/M address 3400H, but is 
placed into memory at 980H by the SYSGEN program. Thus, the negative bias, de¬ 
noted by n, satisfies 

3400H + n = 980H, or n =980H - 3400H 

Assuming two’s complement arithmetic, n = D580H, which can be checked by 

3400H + D580H = 10980H = 0980H (ignoring high-order overflow). 

Note that for larger systems, n satisfies 

(3400H + b) + n = 980H,or 
n = 980H - (3400H + b), or 
n = D580H - b 

The value of n for common CP/M systems is given below. 


Table 6-2. Common Values for CP/M Systems 


Memory Size 

BIASb 

Negative Offset n 

20K 

0000H 

D580H - 0000H = D580H 

24K 

1000H 

D580H - 1000H = C580H 

32K 

3000H 

D580H - 3000H = A580H 

40K 

5000H 

D580H - 5000H = 8580H 

48K 

7000H 

D580H - 7000H = 6580H 

56K 

9000H 

D580H - 9000H = 4580H 

62K 

A800H 

D580H - A800H = 2D80H 

64K 

B000H 

D580H - B000H = 2580H 
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If you want to locate the address x within the memory image loaded under DDT in a 
20K system, first type 

H x t n Hexadecimal sum and difference 

and DDT responds with the value of x + n (sum) and x —n (difference). The first 
number printed by DDT is the actual memory address in the image where the data or 
code is located. For example, the following DDT command: 

H 3 4 0 0 > D 5 8 0 

produces 980H as the sum, which is where the CCP is located in the memory image 
under DDT. 

Type the L command to disassemble portions of the BIOS located at 
(4A00H + b) — n, >Jvhich, when one uses the H command, produces an actual address of 
1F80H. The disassembly command would thus be as follows: 

L1F80 

It is now necessary to patch in the CBOOT and CBIOS routines. The BOOT resides at 
location 0900H in the memory image. If the actual load address is n, then to calculate 
the bias (m), type the command: 

H 0 0 0 t n Subtract load address from target address. 

The second number typed by DDT in response to the command is the desired bias 
(m). For example, if the BOOT executes at 0080H, the command 

H 8 0 0>80 

produces 

0880 0880 Sum and difference in hex. 

Therefore, the bias m would be 0880H. To read-in the BOOT, give the command: 

I CBOOT . HEX Input file CBOOT.HEX 

Then 

Rm Read CBOOT with a bias of m (= 900H — n). 
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Examine the CBOOT with 


L 9 0 0 


You are now ready to replace the CBIOS by examining the area at 1F80H, where the 
original version of the CBIOS resides, and then typing 

ICBIOS.HEX Ready the hex file for loading. 

Assume that the CBIOS is being integrated into a 20K CP/M system and thus 
originates at location 4A00H. To locate the CBIOS properly in the memory image 
under DDT, you must apply the negative bias n for a 20K system when loading the hex 
file. This is accomplished by typing 

RD580 Read the file with bias D580H. 


Upon completion of the read, reexamine the area where the CBIOS has been loaded 
(use an L1F80 command) to ensure that it is properly loaded. When you are satisfied 
that the change has been made, return from DDT using a CTRL-C or, GO command. 


SYSGEN is used to replace the patched memory image back onto a disk (you use a 
test disk until sure of the patch) as shown in the following interaction: 


SYSGEN 

SYSGEN VERSION 2.0 

SOURCE DRIVE NAME 
(OR RETURN TO SKIP) 


DESTINATION DRIVE NAME 
(OR RETURN TO REBOOT) 


Start the SYSGEN program. 

Sign-on message from SYSGEN. 

Respond with a carriage return to skip the 
CP/M read operation because the system is 
already in memory. 

Respond with B to write the new system to the 
disk in drive B. 


DESTINATION ON B t Place a scratch disk in drive B, then press RE- 

THEN TYPE RETURN TURN. 


FUNCTION COMPLETE 
DESTINATION DRIVE NAME 
(OR RETURN TO REBOOT) 
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Place the scratch disk in 

drive A, then perform a cold start to bring up the newly- 


configured CP/M system. 



The new CP/M system is then tested and the Digital Research copyright notice is 
placed on the disk, as specified in the Licensing Agreement: 

l§nm 




Copyright ( c ) t 1979 


Digital Research 


fmm 




6.4 Sample GETSYS and PUTSYS Programs 

liRRRIRl 

The following program provides a framework for the GETSYS and PUTSYS pro¬ 
grams referenced in Sections 6.1 and 6.2. To read and write the specific sectors, you 
must insert the READSEC and WRITESEC subroutines. 


? GETSYS PROGRAM - READ 

TRACKS 0 AND 1 TO MEMORY AT 3380H 


5 REGISTER 

USE 


? A 

(SCRATCH REGISTER) 


5 B 

TRACK COUNT <0* 1) 


5 C 

SECTOR COUNT (1»2»... »26) 

plipH} 

; DE 

(SCRATCH REGISTER PAIR) 


5 HL 

LOAD ADDRESS 


; sp 

SET TO STACK ADDRESS 

r 

5 

START: LXI SP»3380H 

ISET STACK POINTER TO SCRATCH 



5 AREA 

_ 

LXI H»33B0H 

5SET BASE LOAD ADDRESS 

' 

mmi B#0 

5START WITH TRACK 0 


RDTRK: 

5 READ NEXT TRACK (INITIALLY 0) 


MM I CT 

5 READ STARTING WITH SECTOR 1 
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RDSEC: 


5READ NEXT SECTOR 

CALL 

READSEC 

5USER-SUPPLIED SUBROUTINE 

LXI 

D #128 

5MOVE LOAD ADDRESS TO NEXT 1/2 



5 PAGE 

DAD 

D 

;HL = HL + 128 

INR 

C 

5SECTOR = SECTOR + 1 

MOV 

A #C 

5CHECK FOR END OF TRACK 

CPI 

27 


JC 

RDSEC 

5CARRY GENERATED IF SECTOR <27 

5 

1 ARRIVE HERE 

AT END OF 

TRACK * MOVE TO NEXT TRACK 

INR 

B 


MOV 

A #B 

5TEST FOR LAST TRACK 

CPI 

2 


JC 

RDTRK 

SCARRY GENERATED IF TRACK <2 


i USER-SUPPLIED SUBROUTINE TO READ THE DISK 
READSEC: 

5 ENTER WITH TRACK NUMBER IN REGISTER B* 
SECTOR NUMBER IN REGISTER C» AND 

? ADDRESS TO FILL IN HL 


PUSH B SSAVE B AND C REGISTERS 

PUSH H SSAVE HL REGISTERS 


perform disK read at this point* branch to 
label START if an error occurs 
****************************************** 
POP H 5RECOVER HL 

POP B IRECOVER B AND C REGISTERS 

RET 5BACK TO MAIN PROGRAM 

END START 


Listing 6-1. GETSYS Program 
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This program is assembled and listed in Appendix B for reference purposes, with an 
assumed origin of 100H. The hexadecimal operation codes that are listed on the left 
might be useful if the program has to be entered through the panel switches. 

The PUTSYS program can be constructed from GETSYS by changing only a few 
operations in the GETSYS program given above, as shown in Appendix C. The register 
pair HL becomes the dump address, next address to write, and operations on these 
registers do not change within the program. The READSEC subroutine is replaced by a 
WRITESEC subroutine, which performs the opposite function; data from address HL 
is written to the track given by register B and sector given by register C. It is often useful 
to combine GETSYS and PUTSYS into a single program during the test and develop¬ 
ment phase, as shown in Appendix C. 


6.5 Disk Organization 

The sector allocation for the standard distribution version of CP/M is given here for 
reference purposes. The first sector contains an optional software boot section (see the 
table on the following page). Disk controllers are often set up to bring track 0, sector 1, 
into memory at a specific location, often location 0000H. The program in this sector, 
called BOOT, has the responsibility of bringing the remaining sectors into memory 
starting at location 3400H + b. If the controller does not have a built-in sector load, the 
program in track 0, sector 1 can be ignored. In this case, load the program from track 0, 
sector 2, to location 3400H + b. 

As an example, the Intel MDS-800 hardware cold start loader brings track 0, sector 
1, into absolute address 3000H. Upon loading this sector, control transfers to location 
3000H, where the bootstrap operation commences by loading the remainder of track 0 
and all of track 1 into memory, starting at 3400H + b. Note that this bootstrap loader 
is of little use in a non-MDS environment, although it is useful to examine it because 
some of the boot actions will have to be duplicated in the user’s cold start loader. 
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Table 6-3. 

CP/M Disk Sector Allocation 

Track # 

Sector 

Page # 

Memory Address 

CP/M Module name 

00 

01 


(boot address) 

Cold Start Loader 

00 

02 

00 

3400H +b 

CCP 

’ 

03 

’ 

3480H +b 


’ 

04 

01 

3500H +b 


’ 

05 

’ 

3580H + b 


> 

06 

02 

3600H +b 


’ 

07 

’ 

3680H +b 

* 

’ 

08 

03 

3700H +b 

* 

’ 

09 

’ 

3780H +b 

> 

’ 

10 

04 

3800H +b 

* 

’ 

11 

’ 

3880H +b 

* 

’ 

12 

05 

3900H +b 

* 


13 

’ 

3980H +b 

* 

’ 

14 

06 

3A00H + b 

> 

’ 

15 

’ 

3A80H + b 


’ 

16 

07 

3B00H + b 

* 

00 

17 

’ 

3B80H + b 

CCP 

00 

18 

08 

3C00H + b 

BDOS 

’ 

19 

’ 

3C80H + b 


’ 

20 

09 

3D00H + b 

* 

’ 

21 

’ 

3D80H + b 


’ 

22 

10 

3E00H +b 



23 

* 

3E80H +b 


* 

24 

11 

3F00H +b 


’ 

25 

’ 

3F80H +b 

* 

’ 

26 

12 

4000H + b 


01 

01 


4080H +b 



02 

13 

4100H + b 


’ 

03 


4180H + b 


’ 

04 

14 

4200H +b 

> 

’ 

05 

’ 

4280H +b 


’ 

06 

15 

4300H +b 


’ 

07 


4380H +b 


’ 

08 

16 

4400H +b 


’ 

09 

’ 

4480H +b 

> 

’ 

10 

17 

4500H +b 


’ 

11 

5 

4580H + b 
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Table 6-3. (continued) 



Track # 

Sector 

Page # 

Memory Address 

CP/M Module name 



12 

18 

4600H + b 




13 


4680H + b 



14 

19 

4700H + b 




15 

' 

4780H + b 




16 

20 

4800H +b 




17 

' 

4880H + b 




18 

21 

4900H + b 

' 


01 

19 


4900H +b 

BDOS 


07 

20 

22 

4A00H + b 

BIOS 

' 

21 


4A80H + b 

1 



22 

23 

4B00H + b 




23 


4B80H + b 



24 

24 

4CO0H + b 



01 

25 


4C80H + b 

BIOS 

ppllgl 

01 

02-76 

26 

01-26 

25 

4D00H + b 

BIOS 

(directory and data) 


6.6 


The BIOS Entry Points 



The entry points into the BIOS from the cold start loader and BDOS are detailed 
below. Entry to the BIOS is through a jump vector located at 4A00H + b, as shown 
below. See Appendixes A and B. The jump vector is a sequence of 17 jump instructions 
that send program control to the individual BIOS subroutines. The BIOS subroutines 
might be empty for certain functions (they might contain a single RET operation) 
during reconfiguration of CP/M, but the entries must be present in the jump vector. 


f*> The jump vector at 4A00H + b takes the form shown below, where the individual 
jump addresses are given to the left: 


1 

/lA00H+b 

JMP BOOT 

5ARRIVE HERE FROM COLD 

START LOAD 


4A03H+b 

JMP WB00T 

lARRIVE HERE FOR WARM START 


4A0GH+b 

JMP CONST 

ICHECK FOR CONSOLE CHAR 
READY 
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4A09H+b 

JMP CONIN 

;read console character in 

flAOCH+b 

JMP CONOUT 

;WRITE CONSOLE CHARACTER 

OUT 

flAOFH+b 

JMP LIST 

;WRITE LISTING CHARACTER OUT 

4A12H+b 

JMP PUNCH 

IWRITE CHARACTER TO PUNCH 

DEVICE 

4A15H+b 

JMP READER 

5READ READER DEVICE 

AAlBH+b 

JMP HOME 

5M0VE TO TRACK 00 ON 

SELECTED DISK 

flAIBH+b 

JMP SELDSK 

5SELECT DISK DRIVE 

4AlEH+b 

JMP SETTRK 

iSET TRACK NUMBER 

4A21H+b 

JMP SETSEC 

iSET SECTOR NUMBER 

4A24H+b 

JMP SETDMA 

iSET DMA ADDRESS 

4A27H+b 

JMP READ 

5READ SELECTED SECTOR 

4A2AH+b 

JMP WRITE 

;WRITE SELECTED SECTOR 

4A2DH+b 

JMP LISTST 

iRETURN LIST STATUS 

4A30H+b 

JMP SECTRAN 

;SECTOR TRANSLATE 


SUBROUTINE 

Listing 6-2. BIOS Entry Points 


Each jump address corresponds to a particular subroutine that performs the specific 
function, as outlined below. There are three major divisions in the jump table: the 
system reinitialization, which results from calls on BOOT and WBOOT; simple charac¬ 
ter I/O, performed by calls on CONST, CONIN, CONOUT, LIST, PUNCH, READ¬ 
ER, and LISTST; and disk I/O, performed by calls on HOME, SELDSK, SETTRK, 
SETSEC, SETDMA, READ, WRITE, and SECTRAN. 
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All simple character I/O operations are assumed to be performed in ASCII, upper- 
and lower-case, with high-order (parity bit) set to zero. An end-of-file condition for an 
input device is given by an ASCII CTRL-Z (1AH). Peripheral devices are seen by CP/M 
as logical devices and are assigned to physical devices within the BIOS. 

To operate, the BDOS needs only the CONST, CONIN, and CONOUT subroutines. 
LIST, PUNCH, and READER can be used by PIP, but not the BDOS. Further, the 
LISTST entry is currently used only by DESPOOL, the print spooling utility. Thus, the 
initial version of CBIOS can have empty subroutines for the remaining ASCII devices. 

The following list describes the characteristics of each device. 

■ CONSOLE is the principal interactive console that communicates with the 
operator and it is accessed through CONST, CONIN, and CONOUT. Typical¬ 
ly, the CONSOLE is a device such as a CRT or teletype. 

■ LIST is the principal listing device. If it exists on the user’s system, it is usually a 
hard-copy device, such as a printer or teletype. 

■ PUNCH is the principal tape punching device. If it exists, it is normally a 
high-speed paper tape punch or teletype. 

■ READER is the principal tape reading device, such as a simple optical reader or 
teletype. 

A single peripheral can be assigned as the LIST, PUNCH, and READER device 
simultaneously. If no peripheral device is assigned as the LIST, PUNCH, or READER 
device, the CBIOS gives an appropriate error message so that the system does not hang 
if the device is accessed by PIP or some other user program. Alternately, the PUNCH 
and LIST routines can just simply return, and the READER routine can return with a 
1 AH (CTRL-Z) in register A to indicate immediate end-of-file. 

For added flexibility, you can optionally implement the IOBYTE function, which 
allows reassignment of physical devices. The IOBYTE function creates a mapping of 
logical-to-physical devices that can be altered during CP/M processing, see the STAT 
command in Section 1.6.1. 
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The definition of the IOBYTE function corresponds to the Intel standard as follows: 
a single location in memory, currently location 0003H, is maintained, called IOBYTE, 
which defines the logical-to-physical device mapping that is in effect at a particular 
time. The mapping is performed by splitting the IOBYTE into four distinct fields of two 
bits each, called the CONSOLE, READER, PUNCH, and LIST fields, as shown in the 
following figure. 


IOBYTE AT 003H 


MOST SIGNIFICANT 
LIST PUNCH 

BITS 6, 7 BITS 4, 5 


LEAST SIGNIFICANT 
READER CONSOLE 

BITS 2, 3 BITS 0,1 


Figure 6-1. IOBYTE Fields 


The value in each field can be in the range 0—3, defining the assigned source or 
destination of each logical device. Table 6-4 gives the values that can be assigned to 
each field. 


Table 6-4. IOBYTE Field Values 


Value 

Meaning 

CONSOLE field (bits 0,1) 

0 

console is assigned to the console printer device (TTY:) 

1 

console is assigned to the CRT device (CRT:) 

2 

batch mode: use the READER as the CONSOLE input, and the LIST 


device as the CONSOLE output (BAT:) 

3 

user-defined console device (UC1:) 

READER field (bits 2,3) 

0 

READER is the teletype device (TTY:) 

1 

READER is the high speed reader device (PTR:) 

2 

user-defined reader #1 (UR1:) 

3 

user-defined reader #2 (UR2:) 


6-18 


M DIGITAL RESEARCH 




CP/M Operating System Manual 


6.6 BIOS Entry Points 


Table 6-4. (continued) 


Value 

Meaning 

PUNCH field (bits 4,5) 

0 

PUNCH is the teletype device (TTY:) 

1 

PUNCH is the high speed punch device (PTP:) 

2 

user-defined punch # I (UP1:) 

3 

user-defined punch #2 (UP2:) 

LIST field (bits 6,7) 

0 

LIST is the teletype device (TTY:) 

1 

LIST is the CRT device (CRT:) 

2 

LIST is the line printer device (LPT:) 

3 

user-defined list device (UL1:) 


The implementation of the IOBYTE is optional and effects only the organization of 
the CBIOS. No CP/M systems use the IOBYTE (although they tolerate the existence of 
the IOBYTE at location 0003H) except for PIP, which allows access to the physical 
devices, and STAT, which allows logical-physical assignments to be made or displayed. 
For more information see Section 1. In any case the IOBYTE implementation should be 
omitted until the basic CBIOS is fully implemented and tested; then you should add the 
IOBYTE to increase the facilities. 

Disk I/O is always performed through a sequence of calls on the various disk access 
subroutines that set up the disk number to access, the track and sector on a particular 
disk, and the Direct Memory Access (DMA) address involved in the I/O operation. 
After all these parameters have been set up, a call is made to the READ or WRITE 
function to perform the actual I/O operation. 

There is often a single call to SELDSK to select a disk drive, followed by a number of 
read or write operations to the selected disk before selecting another drive for subse¬ 
quent operations. Similarly, there might be a single call to set the DMA address, 
followed by several calls that read or write from the selected DMA address before the 
DMA address is changed. The track and sector subroutines are always called before the 
READ or WRITE operations are performed. 
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The READ and WRITE routines should perform several retries (10 is standard) 
before reporting the error condition to the BDOS. If the error condition is returned to 
the BDOS, it reports the error to the user. The HOME subroutine might or might not 
actually perform the track 00 seek, depending upon controller characteristics; the 
important point is that track OCThas been selected for the next operation and is often 
treated in exactly the same manner as SETTRK with a parameter of 00. 


The following table describes the exact responsibilities of each BIOS entry point 
subroutine. 


Table 6-5. BIOS Entry Points 


Entry Point 

Function 

BOOT 

The BOOT entry point gets control from the cold start loader and 
is responsible for basic system initialization, including sending a 
sign-on message, which can be omitted in the first version. If the 
IOBYTE function is implemented, it must be set at this point. The 
various system parameters that are set by the WBOOT entry point 
must be initialized, and control is transferred to the CCP at 
3400 + b for further processing. Note that register C must be set 
to zero to select drive A. 

WBOOT 

The WBOOT entry point gets control when a warm start occurs. 

A warm start is performed whenever a user program branches to 
location 0000H, or when the CPU is reset from the front panel. 
The CP/M system must be loaded from the first two tracks of 
drive A up to, but not including, the BIOS, or CBIOS, if the user 
has completed the patch. System parameters must be initialized as 
follows: 


location 0,1,2 Set to JMP WBOOT for warm starts 

(000H: JMP 4A03H + b) 


location 3 Set initial value of IOBYTE, if implemented 

in the CBIOS 


location 4 High nibble = current user no; low nibble 

= current drive 
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Table 6-5. (continued) 


Entry Point 

Function 


location 5,6,7 Set to JMP BDOS, which is the primary 

entry point to CP/M for transient pro¬ 
grams. (0005H: JMP 3C06H + b) 


Refer to Section 6.9 for complete details of page zero use. Upon 
completion of the initialization, the WBOOT program must 
branch to the CCP at 3400H + b to restart the system. Upon entry 
to the CCP, register C is set to the drive to select after system 
initialization. The WBOOT routine should read location 4 in 
memory, verify that is a legal drive, and pass it to the CCP in 
register C. 

CONST 

You should sample the status of the currently assigned console 
device and return OFFH in register A if a character is ready to read 
and 00H in register A if no console characters are ready. 

CONIN 

The next console character is read into register A, and the parity 
bit is set, high-order bit, to zero. If no console character is ready, 
wait until a character is typed before returning. 

CONOUT 

The character is sent from register C to the console output device. 
The character is in ASCII, with high-order parity bit set to zero. 
You might want to include a time-out on a line-feed or carriage 
return, if the console device requires some time interval at the end 
of the line (such as a TI Silent 700 terminal). You can filter out 
control characters that cause the console device to react in a 
strange way (CTRL-Z causes the Lear-Siegler terminal to clear the 
screen, for example). 

LIST 

The character is sent from register C to the currently assigned 
listing device. The character is in ASCII with zero parity bit. 

PUNCH 

The character is sent from register C to the currently assigned 
punch device. The character is in ASCII with zero parity. 

READER 

The next character is read from the currently assigned reader 
device into register A with zero parity (high-order bit must be 
zero); an end-of-file condition is reported by returning an ASCII 
CTRL-Z(IAH). 
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Table 6-5. (continued) 

Entry Point 

Function 

HOME 

The disk head of the currently selected disk (initially disk A) is 
moved to the track 00 position. If the controller allows access to 
the track 0 flag from the drive, the head is stepped until the track 0 
flag is detected. If the controller does not support this feature, the 
HOME call is translated into a call to SETTRK with a parameter 
of 0. 

SELDSK 

The disk drive given by register C is selected for further opera¬ 
tions, where register C contains 0 for drive A, 1 for drive B, and so 
on up to 15 for drive P (the standard CP/M distribution version 
supports four drives). On each disk select, SELDSK must return in 
HL the base address of a 16-byte area, called the Disk Parameter 
Header, described in Section 6.10. For standard floppy disk 
drives, the contents of the header and associated tables do not 
change; thus, the program segment included in the sample CBIOS 
performs this operation automatically. 


If there is an attempt to select a nonexistent drive, SELDSK re¬ 
turns HL = 0000H as an error indicator. Although SELDSK must 
return the header address on each call, it is advisable to postpone 
the physical disk select operation until an I/O function (seek, read, 
or write) is actually performed, because disk selects often occur 
without ultimately performing any disk I/O, and many controllers 
unload the head of the current disk before selecting the new drive. 
This causes an excessive amount of noise and disk wear. The least 
significant bit of register E is zero if this is the first occurrence of 
the drive select since the last cold or warm start. 

SETTRK 

Register BC contains the track number for subsequent disk ac¬ 
cesses on the currently selected drive. The sector number in BC is 
the same as the number returned from the SECTRAN entry point. 
You can choose to seek the selected track at this time or delay the 
seek until the next read or write actually occurs. Register BC can 
take on values in the range 0-76 corresponding to valid track 
numbers for standard floppy disk drives and 0—65535 for non¬ 
standard disk subsystems. 




(•ttWSKj, 
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Table 6-5. (continued) 


Entry Point 

Function 

SETSEC 

Register BC contains the sector number, 1 through 26, for subse¬ 
quent disk accesses on the currently selected drive. The sector 
number in BC is the same as the number returned from the SEC- 


TRAN entry point. You can choose to send this information to 
the controller at this point or delay sector selection until a read or 


write operation occurs. 

SETDMA 

Register BC contains the DMA (Disk Memory Access) address for 
subsequent read or write operations. For example, if B = 00H 
and C = 80H when SETDMA is called, all subsequent read op¬ 
erations read their data into 80H through OFFH and all subse¬ 
quent write operations get their data from 80H through OFFH, 
until the next call to SETDMA occurs. The initial DMA address is 
assumed to be 80H. The controller need not actually support 
Direct Memory Access. If, for example, all data transfers are 
through I/O ports, the CBIOS that is constructed uses the 128- 
byte area starting at the selected DMA address for the memory 
buffer during the subsequent read or write operations. 

READ 

Assuming the drive has been selected, the track has been set, and 
the DMA address has been specified, the READ subroutine 
attempts to read one sector based upon these parameters and 
returns the following error codes in register A: 


0 no errors occurred 


1 nonrecoverable error condition occurred 


Currently, CP/M responds only to a zero or nonzero value as the 
return code. That is, if the value in register A is 0, CP/M assumes 
that the disk operation was completed properly. IF an error occurs 
the CBIOS should attempt at least 10 retries to see if the error is 
recoverable. When an error is reported the BDOS prints the mes¬ 
sage BDOS ERR ONx: BAD SECTOR. The operator then has the 
option of pressing a carriage return to ignore the error, or CTRL- 
C to abort. 
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Table 6-5. (continued) 

Entry Point 

Function 

WRITE 

Data is written from the currently selected DMA address to the 
currently selected drive, track, and sector. For floppy disks, the 
data should be marked as nondeleted data to maintain compati¬ 
bility with other CP/M systems. The error codes given in the 
READ command are returned in register A, with error recovery 
attempts as described above. 

LISTST 

You return the ready status of the list device used by the DE¬ 
SPOOL program to improve console response during its opera¬ 
tion. The value 00 is returned in A if the list device is not ready to 
accept a character and OFFH if a character can be sent to the 
printer. A 00 value should be returned if LIST status is not im¬ 
plemented. 

SECTRAN 

Logical-to-physical sector translation is performed to improve the 
overall response of CP/M. Standard CP/M systems are shipped 
with a skew factor of 6, where six physical sectors are skipped 
between each logical read operation. This skew factor allows 
enough time between sectors for most programs to load their 
buffers without missing the next sector. In particular computer 
systems that use fast processors, memory, and disk subsystems, 
the skew factor might be changed to improve overall response. 
However, the user should maintain a single-density IBM- 
compatible version of CP/M for information transfer into and out 
of the computer system, using a skew factor of 6. 


In general, SECTRAN receives a logical sector number relative to 
zero in BC and a translate table address in DE. The sector number 
is used as an index into the translate table, with the resulting 
physical sector number in HL. For standard systems, the table and 
indexing code is provided in the CBIOS and need not be changed. 


i'lrJW, ' ^ 
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6.7 A Sample BIOS 

F* The program shown in Appendix B can serve as a basis for your first BIOS. The 
simplest functions are assumed in this BIOS, so that you can enter it through a front 
panel, if absolutely necessary. You must alter and insert code into the subroutines for 
pm CONST, CONIN, CONOUT, READ, WRITE, and WAITIO subroutines. Storage is 

- - reserved for user-supplied code in these regions. The scratch area reserved in page zero 

(see Section 6.9) for the BIOS is used in this program, so that it could be implemented in 
pun ROM, if desired. 

Once operational, this skeletal version can be enhanced to print the initial sign-on 
message and perform better error recovery. The subroutines for LIST, PUNCH, and 
i 7 READER can be filled out and the IOBYTE function can be implemented. 


6.8 A Sample Cold Start Loader 




The program shown in Appendix E can serve as a basis for a cold start loader. The 
disk read function must be supplied by the user, and the program must be loaded 
somehow starting at location 0000. Space is reserved for the patch code so that the 
total amount of storage required for the cold start loader is 128 bytes. 

Eventually, you might want to get this loader onto the first disk sector (track 0, sector 
1) and cause the controller to load it into memory automatically upon system start up. 
Alternatively, the cold start loader can be placed into ROM, and above the CP/M 
system. In this case, it is necessary to originate the program at a higher address and key 
in a jump instruction at system start up that branches to the loader. Subsequent warm 
starts do not require this key-in operation, because the entry point WBOOT gets 
control, thus bringing the system in from disk automatically. The skeletal cold start 
loader has minimal error recovery, which might be enhanced in later versions. 
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6.9 Reserved Locations in Page Zero 

Main memory page zero, between locations 00H and OFFH, contains several seg¬ 
ments of code and data that are used during CP/M processing. The code and data areas 
are given in the following table. 


Table 6-6. Reserved Locations in Page Zero 


Locations 

Contents 

000H-0002H 

Contains a jump instruction to the warm start entry loca¬ 
tion 4A03H-f-b. This allows a simple programmed re¬ 
start (JMP 0000H) or manual restart from the front 
panel. 

0003H-0003H 

Contains the Intel standard IOBYTE is optionally in¬ 
cluded in the user’s CBIOS (refer to Section 6.6). 

0004H-0004H 

Current default drive number (0 = A,. . .,15 = P). 

0005H-0007H 

Contains a jump instruction to the BDOS and serves two 
purposes: JMP 0005H provides the primary entry point 
to the BDOS, as described in Section 5, and LHLD 
0006H brings the address field of the instruction to the 
HL register pair. This value is the lowest address in mem¬ 
ory used by CP/M, assuming the CCP is being overlaid. 
The DDT program changes the address field to reflect the 
reduced memory size in debug mode. 

0008H-0027H 

Interrupt locations 1 through 5 not used. 

0030H-0037H 

Interrupt location 6 (not currently used) is reserved. 

0038H-003AH 

Restart 7; contains a jump instruction into the DDT or 
SID program when running in debug mode for pro¬ 
grammed breakpoints, but is not otherwise used by 
CP/M. 

003BH-003FH 

Not currently used; reserved. 
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Table 6-6. (continued) 


Locations 

Contents 

0040H-004FH 

A 16-byte area reserved for scratch by CBIOS, but is not 
used for any purpose in the distribution version of CP/M. 

0050H-005BH 

Not currently used; reserved. 

005CH-007CH 

Default File Control Block produced for a transient pro¬ 
gram by the CCP. 

007DH-007FH 

Optional default random record position. 

0080H-00FFH 

Default 128-byte disk buffer, also filled with the com¬ 
mand line when a transient is loaded under the CCP. 


This information is set up for normal operation under the CP/M system, but can be 
overwritten by a transient program if the BDOS facilities are not required by the 
transient. 

If, for example, a particular program performs only simple I/O and must begin 
execution at location 0, it can first be loaded into the TPA, using normal CP/M 
facilities, with a small memory move program that gets control when loaded. The 
memory move program must get control from location 0100H, which is the assumed 
beginning of all transient programs. The move program can then proceed to the entire 
memory image down to location 0 and pass control to the starting address of the 
memory load. 

If the BIOS is overwritten or if location 0, containing the warm start entry point, is 
overwritten, the operator must bring the CP/M system back into memory with a cold 
start sequence. 
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6.10 Disk Parameter Tables 


Tables are included in the BIOS that describe the particular characteristics of the disk 
subsystem used with CP/M. These tables can be either hand-coded, as shown in the 
sample CBIOS in Appendix B, or automatically generated using the DISKDEF macro 
library, as shown in Appendix F. The purpose here is to describe the elements of these 
tables. 


In general, each disk drive has an associated (16-byte) disk parameter header that 
contains information about the disk drive and provides a scratch pad area for certain 
BDOS operations. The format of the disk parameter header for each drive is shown in 
Figure 6-2, where each element is a word (16-bit) value. 


fi«p^ 


DISK PARAMETER HEADER 


XLT 

0000 

0000 

0000 

DIRBUF 

DPB 

CSV 

ALV 

16B 

16B 

16B 

16B 

16B 

16B 

16B 

16B 




Figure 6-2. Disk Parameter Header Format 


The meaning of each Disk Parameter Header (DPH) element is detailed in Table 6-7. 


Table 6-7. Disk Parameter Headers 


Disk Parameter 


Header 

Meaning 

XLT 

Address of the logical-to-physical translation vector, if used 
for this particular drive, or the value 0000H if no sector 
translation takes place (that is, the physical and logical sec¬ 
tor numbers are the same). Disk drives with identical sector 
skew factors share the same translate tables. 

0000 

Scratch pad values for use within the BDOS, initial value is 
unimportant. 

DIRBUF 

Address of a 128-byte scratch pad area for directory opera¬ 
tions within BDOS. All DPHs address the same scratch pad 


area. 










6-28 


DIGITAL RESEARCH '* 





CP/M Operating System Manual 6.10 Disk Parameter Tables 


Table 6-7. (continued) 


rm 

Disk Parameter 
Header 

Meaning 


DPB 

Address of a disk parameter block for this drive. Drives with 
identical disk characteristics address the same disk para¬ 
meter block. 


CSV 

Address of a scratch pad area used for software check for 
changed disks. This address is different for each DPH. 


ALV 

Address of a scratch pad area used by the BDOS to keep disk 
storage allocation information. This address is different for 
each DPH. 


Given n disk drives, the DPHs are arranged in a table whose first row of 16 bytes 
corresponds to drive 0, with the last row corresponding to drive n-1. In the following 
figure the label DPBASE defines the base address of the DPH table. 




DPBASE: 


00 

XLT 00 

0000 

0000 

0000 

DIRBUF 

DBP00 

CSV 00 

ALV 00 

01 

XLT01 

0000 

0000 

0000 

DIRBUF 

DBP01 

CSV 01 

ALV 01 


(AND SO ON THROUGH) 


XLTn-1 I 0000 0000 0000 


DIRBUF 


DBPn-1 CSVn-1 


ALVn-1 


Figure 6-3. Disk Parameter Header Table 
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A responsibility of the SELDSK subroutine is to return the base address of the DPH 
for the selected drive. The following sequence of operations returns the table address, n ^ 
with a 0000H returned if the selected drive does not exist. 


NDISKS 

EQU 

4 

INUMBER OF DI! 

SELDSK: 

5SELECT DISK GIVEN 

BY BC 


LSI 

H iCOOOH 

5ERROR CODE 


MOM 

A»C 

1DRIME OK? 


CPI 

NDISKS 

ICY IF SO 


RNC 


IRET IF ERROR 


;no 

ERROR t CONTINUE 


MOM 

L fC 

ILOW(DISK) 


MOM 

H »B 

IHIGH(DISK) 


DAD 

H 

1*2 


DAD 

H 

1*4 


DAD 

H 

1 *8 


DAD 

H 

1*16 


LX I 

D»DPBASE5FIRST DPH 


DAD 

D 

1DPH(DISK) 


RET 








The translation vectors, XLT 00 through XLTn-1, are located elsewhere in the BIOS, 
and simply correspond one-for-one with the logical sector numbers zero through the 
sector count 1. The Disk Parameter Block (DPB) for each drive is more complex. As 
shown in Figure 6-4, particular DPB, that is addressed by one or more DPHs, takes the 
general form: 


SPT 

BSH 

BLM 

EXM 

DSM 

DRM 

ALO 

AL1 

CKS 

OFF 


16B 8B 8B 8B 16B 16B 8B 8B 16B 16B 

Figure 6-4. Disk Parameter Block Format 




where each is a byte or word value, as shown by the 8b or 16b indicator below the field. 
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The following field abbreviations are used in Figure 6-4: 

■ SPT is the total number of sectors per track. 

■ BSH is the data allocation block shift factor, determined by the data block 
allocation size. 

■ BLM is the data allocation block mask (2[BSH-1]). 

■ EXM is the extent mask, determined by the data block allocation size and the 
number of disk blocks. 

■ DSM determines the total storage capacity of the disk drive. 

■ DRM determines the total number of directory entries that can be stored on this 
drive. ALO, AL1 determine reserved directory blocks. 

■ CKS is the size of the directory check vector. 

■ OFF is the number of reserved tracks at the beginning of the (logical) disk. 

The values of BSH and BLM determine the data allocation size BLS, which is not an 
entry in the DPB. Given that the designer has selected a value for BLS, the values of 
BSH and BLM are shown in Table 6-8. 


Table 6-8. BSH and BLM Values 


BLS 

BSH 

BLM 

1,024 

3 

7 

2,048 

4 

15 

4,096 

5 

31 

8,192 

6 

63 

16,384 

7 

127 


where all values are in decimal. The value of EXM depends upon both the BLS and 
whether the DSM value is less than 256 or greater than 255, as shown in Table 6-9. 
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Table 6-9. EXM Values 


BLS 

EXM values 

DSM <256 

DSM>255 

1,024 

0 

N/A 

2,048 

1 

0 

4,096 

3 

1 

8,192 

7 

3 

16,384 

15 

7 





(Mti 

The value of DSM is the maximum data block number supported by this particular 
drive, measured in BLS units. The product (DSM + 1) is the total number of bytes held 
by the drive and must be within the capacity of the physical disk, not counting the 
reserved operating system tracks. 


The DRM entry is the one less than the total number of directory entries that can 
take on a 16-bit value. The values of ALO and AL1, however, are determined by DRM. 
The values ALO and AL1 can together be considered a string of 16-bits, as shown in 
Figure 6-5. 




ALO 

AL1 

i i i i i i i 

i i i i i i i 


00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 

Figure 6-5. ALO and AL1 
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Position 00 corresponds to the high-order bit of the byte labeled ALO and 15 corres¬ 
ponds to the low-order bit of the byte labeled AL1. Each bit position reserves a data 
block for number of directory entries, thus allowing a total of 16 data blocks to be 
assigned for directory entries (bits are assigned starting at 00 and filled to the right until 
position 15). Each directory entry occupies 32 bytes, resulting in the following tabula¬ 
tion: 


Table 6-10. BLS Tabulation 


BLS 

Directory Entries 

1,024 

32 times # bits 

2,048 

64 times # bits 

4,096 

128 times # bits 

8,192 

256 times # bits 

16,384 

512 times # bits 


ppaa, 

Thus, if DRM = 127 (128 directory entries) and BLS = 1024, there are 32 directory 
entries per block, requiring 4 reserved blocks. In this case, the 4 high-order bits of ALO 
are set, resulting in the values ALO = 0F0H and AL1 = 00H. 

The CKS value is determined as follows: if the disk drive media is removable, then 
CKS = (DRM + l)/4, where DRM is the last directory entry number. If the media are 
fixed, then set CKS = 0 (no directory records are checked in this case). 






Finally, the OFF field determines the number of tracks that are skipped at the begin¬ 
ning of the physical disk. This value is automatically added whenever SETTRK is called 
and can be used as a mechanism for skipping reserved operating system tracks or for 
partitioning a large disk into smaller segmented sections. 

To complete the discussion of the DPB, several DPHs can address the same DPB if 
their drive characteristics are identical. Further, the DPB can be dynamically changed 
when a new drive is addressed by simply changing the pointer in the DPH; because the 
BDOS copies the DPB values to a local area whenever the SELDSK function is invoked. 


Returning back to DPH for a particular drive, the two address values CSV and ALV 
!*** remain. Both addresses reference an area of uninitialized memory following the BIOS. 
The areas must be unique for each drive, and the size of each area is determined by the 
values in the DPB. 
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The size of the area addressed by CSV is CKS bytes, which is sufficient to hold the 
directory check information for this particular drive, If CKS = (DRM + l)/4, you must 
reserve (DRM + l)/4 bytes for directory check use. If CKS = 0, no storage is reserved. 

The size of the area addressed by ALV is determined by the maximum number of 
data blocks allowed for this particular disk and is computed as (DSM/8) + 1. 

The CBIOS shown in Appendix B demonstrates an instance of these tables for 
standard 8-inch, single-density drives. It might be useful to examine this program and 
compare the tabular values with the definitions given above. 


6.11 The DISKDEF Macro Library 

A macro library called DISKDEF (shown in Appendix F), greatly simplifies the table 
construction process. You must have access to the MAC macro assembler, of course, to 
use the DISKDEF facility, while the macro library is included with all CP/M 2 distribu¬ 
tion disks. 

A BIOS disk definition consists of the following sequence of macro statements: 


MACLIB 

DISKDEF 

DISKS 

n 

DISKDEF 

0 ,... 

DISKDEF 

1 ,... 

DISKDEF 

n -1 

ENDEF 



where the MACLIB statement loads the DISKDEF.LIB file, on the same disk as the 
BIOS, into MAC’s internal tables. The DISKS macro call follows, which specifies the 
number of drives to be configured with the user’s system, where n is an integer in the 
range 1 to 16. A series of DISKDEF macro calls then follow that define the characteris¬ 
tics of each logical disk, 0 through n - 1, corresponding to logical drives A through P. 
The DISKS and DISKDEF macros generate the in-line fixed data tables described in the 
previous section and thus must be placed in a nonexecutable portion of the BIOS, 
typically directly following the BIOS jump vector. 
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The remaining portion of the BIOS is defined following the DISKDEF macros, with 
the ENDEF macro call immediately preceding the END statement. The ENDEF (End of 
Diskdef) macro generates the necessary uninitialized RAM areas that are located in 
memory above the BIOS. 

The DISKDEF macro call takes the form: 

DISKDEF dn,fsc,lsc,[skf],bls dks,dir,cks,ofs,[0] 
where 

■ dn is the logical disk number, 0 to n - 1. 

■ fsc is the first physical sector number (0 or 1). 

■ lsc is the last sector number. 

■ skf is the optional sector skew factor. 

■ bis is the data allocation block size. 

■ dks is the number of blocks on the disk. 

■ dir is the number of directory entries. 

■ cks is the number of checked directory entries. 

■ ofs is the track offset to logical track 00. 

■ [0] is an optional 1.4 compatibility flag. 

The value dn is the drive number being defined with this DISKDEF macro invoca¬ 
tion. The fsc parameter accounts for differing sector numbering systems and is usually 
0 to 1. The lsc is the last numbered sector on a track. When present, the skf parameter 
defines the sector skew factor, which is used to create a sector translation table accord¬ 
ing to the skew. 

If the number of sectors is less than 256, a single-byte table is created, otherwise each 
translation table element occupies two bytes. No translation table is created if the skf 
parameter is omitted, or equal to 0. 

The bis parameter specifies the number of bytes allocated to each data block, and 
takes on the values 1024, 2048, 4096, 8192, or 16384. Generally, performance in¬ 
creases with larger data block sizes because there are fewer directory references, and 
logically connected data records are physically close on the disk. Further, each direc¬ 
tory entry addresses more data and the BIOS-resident RAM space is reduced. 

The dks parameter specifies the total disk size in bis units. That is, if the bis = 2048 
and dks = 1000, the total disk capacity is 2,048,000 bytes. If dks is greater than 255, 
the block size parameter bis must be greater than 1024. The value of dir is the total 
number of directory entries that might exceed 255, if desired. 


m DIGITAL RESEARCH"' 


6-35 



6.11 The DISKDEF Macro Library 


CP/M Operating System Manual 


The cks parameter determines the number of directory items to check on each 
directory scan and is used internally to detect changed disks during system operation, 
where an intervening cold or warm start has not occurred. When this situation is 
detected, CP/M automatically marks the disk Read-Only so that data is not subse¬ 
quently destroyed. 

As stated in the previous section, the value of cks = dir when the medium is easily 
changed, as is the case with a floppy disk subsystem. If the disk is permanently 
mounted, the value of cks is typically 0, because the probability of changing disks 
without a restart is low. 

The ofs value determines the number of tracks to skip when this particular drive is 
addressed, which can be used to reserve additional operating system space or to simu¬ 
late several logical drives on a single large capacity physical drive. Finally, the [0] 
parameter is included when file compatibility is required with versions of 1.4 that have 
been modified for higher density disks. This parameter ensures that only 16K is allo¬ 
cated for each directory record, as was the case for previous versions. Normally, this 
parameter is not included. 

For convenience and economy of table space, the special form: 

DISKDEF i,j 

gives disk i the same characteristics as a previously defined drive j. A standard four- 
drive, single-density system, which is compatible with version 1.4, is defined using the 
following macro invocations: 


DISKS 4 

DISKDEF 0,1,26,6,1024,243,64,2 

DISKDEF 1,0 

DISKDEF 2,0 

DISKDEF 3,0 

ENDEF 


with all disks having the same parameter values of 26 sectors per track, numbered 1 
through 26, with 6 sectors skipped between each access, 1024 bytes per data block, 243 
data blocks for a total of 243K-byte disk capacity, 64 checked directory entries, and 
two operating system tracks. 
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The DISKS macro generates n DPHs, starting at the DPH table address DPBASE 
generated by the macro. Each disk header block contains sixteen bytes, as described 
above, and correspond one-for-one to each of the defined drives. In the four-drive 
standard system, for example, the DISKS macro generates a table of the form: 


DPBASE EQU$ 

DPEO: DWXLT0,0000H,0000H,0000H,DIRBUF,DPB0,CSV0,ALV0 

DPE1: DW XLT0,0000H,0000H,0000H,D1RBUF,DPB0,CSV 1 ,ALV 1 

DPE2: DW XLT0,0000H,0000H,0000H,DIRBUF,DPB0,CSV2,ALV2 

DPE3: DW XLT0,0000H,0000H,0000H,DIRBUF,DPB0,CSV3,ALV3 


where the DPH labels are included for reference purposes to show the beginning table 
addresses for each drive 0 through 3. The values contained within the DPH are de¬ 
scribed in detail in the previous section. The check and allocation vector addresses are 
generated by the ENDEF macro in the RAM area following the BIOS code and tables. 

Note that if the skf (skew factor) parameter is omitted, or equal to 0, the translation 
table is omitted and a 0000H value is inserted in the XLT position of the DPH for the 
disk. In a subsequent call to perform the logical-to-physical translation, SECTRAN 
receives a translation table address of DE = 0000H and simply returns the original 
logical sector from BC in the HL register pair. 

A translate table is constructed when the skf parameter is present, and the (nonzero) 
table address is placed into the corresponding DPHs. The following, for example, is 
constructed when the standard skew factor skf = 6 is specified in the DISKDEF macro 
call: 


XLTO: 


1,7,13,19,25,5,11,17,23,3,9,15,21 

2,8,14,20,26,6,12,18,24,4,10,16,22 
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Following the ENDEF macro call, a number of uninitialized data areas are defined. 
These data areas need not be a part of the BIOS that is loaded upon cold start, but must 
be available between the BIOS and the end of memory. The size of the uninitialized 
RAM area is determined by EQU statements generated by the ENDEF macro. For a 
standard four-drive system, the ENDEF macro might produce the following EQU 
statement: 


4C72 = 


BEGDAT EQU $ 
(data areas) 


4DB0 = 


ENDDAT EQU $ 


013C = 


DATSIZ EQU $-BEGDAT 


which indicates that uninitialized RAM begins at location 4C72H, ends at 4DB0H-1, 
and occupies 013CFI bytes. You must ensure that these addresses are free for use after 
the system is loaded. 

After modification, you can use the STAT program to check drive characteristics, 
because STAT uses the disk parameter block to decode the drive information. A STAT 
command of the form: 

STAT d:DSK: 

decodes the disk parameter block for drive d (d = A,. . .,P) and displays the following 
values: 


r: 128-byte record capacity 
k: kilobyte drive capacity 
d: 32-byte directory entries 
c: checked directory entries 
e: records/extent 
b: records/block 
s: sectors/track 
t: reserved tracks 
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Three examples of DISKDEF macro invocations are shown below with correspond¬ 
ing STAT parameter values. The last example produces a full 8-megabyte system. 

DISKDEF 0,1,58„2048,256,128,128,2 
r = 4096, k = 512, d = 128, c= 128, e = 256, b=16, s = 58,t = 2 

DISKDEF 0,1,58„2048,1024,300,0,2 
r= 16348, k = 2048, d = 300, c = 0, e= 128, b=16, s = 58,t = 2 

DISKDEF 0,1,58„16348,512,128,128,2 
r = 65536, k = 8192, d = 128, c= 128, e= 1024, b = 128, s = 58, t = 2 


6.12 Sector Blocking and Deblocking 

Upon each call to BIOS WRITE entry point, the CP/M BDOS includes information 
that allows effective sector blocking and deblocking where the host disk subsystem has 
a sector size that is a multiple of the basic 128-byte unit. The purpose here is to present 
a general-purpose algorithm that can be included within the BIOS and that uses the 
BDOS information to perform the operations automatically. 

On each call to WRITE, the BDOS provides the following information in register C: 

0 = (normal sector write) 

1 = (write to directory sector) 

2 = (write to the first sector 

of a new data block) 

Condition 0 occurs whenever the next write operation is into a previously written 
area, such as a random mode record update; when the write is to other than the first 
sector of an unallocated block; or when the write is not into the directory area. 
Condition 1 occurs when a write into the directory area is performed. Condition 2 
occurs when the first record (only) of a newly allocated data block is written. In most 
cases, application programs read or write multiple 128-byte sectors in sequence; thus, 
there is little overhead involved in either operation when blocking and deblocking 
records, because preread operations can be avoided when writing records. 
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Appendix G lists the blocking and deblocking algorithms in skeletal form; this file is 
included on your CP/M disk. Generally, the algorithms map all CP/M sector read 
operations onto the host disk through an intermediate buffer that is the size of the host 
disk sector. Throughout the program, values and variables that relate to the CP/M 
sector involved in a seek operation are prefixed by sek, while those related to the host 
disk system are prefixed by hst. The equate statements beginning on line 29 of Appen¬ 
dix G define the mapping between CP/M and the host system, and must be changed if 
other than the sample host system is involved. 

The entry points BOOT and WBOOT must contain the initialization code starting 
on line 57, while the SELDSK entry point must be augmented by the code starting on 
line 65. Note that although the SELDSK entry point computes and returns the Disk 
Parameter Header address, it does not physically select the host disk at this point (it is 
selected later at READHST or WRITEHST). Further, SETTRK and SETMA simply 
store the values, but do not take any other action at this point. SECTRAN performs a 
trivial function of returning the physical sector number. 






The principal entry points are READ and WRITE, starting on lines 110 and 125, 
respectively. These subroutines take the place of your previous READ and WRITE 
operations. 


The actual physical read or write takes place at either WRITEHST or READHST, 
where all values have been prepared: hstdsk is the host disk number, hsttrk is the host 
track number, and hstsec is the host sector number, which may require translation to 
physical sector number. You must insert code at this point that performs the full sector 
read or write into or out of the buffer at hstbuf of length hstsiz. All other mapping 
functions are performed by the algorithms. 

This particular algorithm was tested using an 80-megabyte hard disk unit that was 
originally configured for 128-byte sectors, producing approximately 35 megabytes of 
formatted storage. When configured for 512-byte host sectors, usable storage increased 
to 57 megabytes, with a corresponding 400% improvement in overall response. In this 
situation, there is no apparent overhead involved in deblocking sectors, with the advan¬ 
tage that user programs still maintain 128-byte sectors. This is primarily because of the 
information provided by the BDOS, which eliminates the necessity for preread opera- 
tions. 


End of Section 6 
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Appendix A 

The MDS Basic Input/Output System 

(BIOS) 

This listing has been printed broadside on the page, so that you can easily read the 
entire listing. 
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S3 

S3 

S3 

3 

S3 

3 

3 

3 

3 





J DIGITAL RESEARCH" 


B-6 









_i=j -O _i=i 

==3- ==3- ==3- 


==3 ==3- CD 

c-j m n 

jj jj jj 

== 3 - == 3 - == 3 - 


cn cn 

o 

ro co 
n n =o- 

jZj jZj jTi 

=3- 


cn 


O 


m 

-1=1 


o ^ c-j n ^ ltj cq i ■ go cn o —• 

CDCOCOOOCOCDCOCQCDCOCncn 
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listst: 5return list status (0 if not ready* 1 if ready) 
4t>4b af xra a 50 is always oK to return 
4b4c c9 ret 




punch: ipunch character from register c 

4b4d 79 mou a t c '^character to register 

flbfle c9 ret 5nul1 subroutine 


3 

o >. 

s= ** 


^ (D 


E 

HI CD 

S 


■»—i cn 
•h rd 


O •- 
O 

r—I 




O +J CJ 


CD -i-l 


\ O {Z 


rH P- 

n cd cn 
n ai o 


IMNj 


ojn^mmr^mcno-HCvjn'a-mcor-'Cocno—<tNi 

cncncncncncncncnoooooooooo—<—«—• 

' CM CM CM CM N C\l N CM CM C\l CM CM IN 
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ispace 





240 setsec: ?set sector siuen by register c 

241 4b92 79 mov a> c 

242 4b93 32et«4c sta sector 

243 4b9G ds lOh ispace for sector select 

244 4ba6 c9 ret 


JJ ^ Ti Ql 

■c "o 

in ti n3 -n 


co cn o 

ns na ns ns ns 

X .Q Jj jD jj 

^ ^ ==5 'O’ 


^ ^ ^ ^ 


in cd r- cd cn O' — < c-j n^incor^cDcoo-i cj n ^ in m h oo m 

53 53 ^ ^ ^ in in in ITj ITj ITj in in in rj CD LD 0 CD CD CO 0 CO LD CD 

C-J C-J C J C-J C'J C-J C-J C-J C-J C-J C-J C-J C-J C J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J 
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cu CD 
Cl o 

cn CO CD 

Ol (D CD 
_lZl o o 
=3- ==T 


CD JOl T3 *- 
CD CD CD CD 
CJ o o o 
=3- =3- ^ =3- 


c- —< c--j n ^ ifi cd oo 

i^r^r^r-r->r-r-r-r- 
C-J C-J C-J C-J C-J C-J C-J C-J C-J 



cn o t-h c- j n lo cd co in o 

I^CDCOCDQOCDODCOOOOOCOCDCD 
C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J 
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OJ OJ HI Ol 


0)010)0) 


ro ro ro ro 


010)0)0) 


o jCi in ro ro ro ro 


‘COCQCCICD 

ncnnn—< 


U1 O) T? TJ T? 


-• -• TO 
XT XT £Z 
0 ) 0 ) 0 ) 


O O O O 


-CiTorororarocjcJCJCJ 


O O' O' ■+- O) TO o cj o CJ 

■+-■+- 0- OO ro O oi ■+- O' ' 

o O-O-l-lTO-OTOT? O) O) 


II 

O CJ CJ 

oj xm oj 

OJ 1H OJ 

=cr o =^r 


n n itj 

CD CD CD CD 

oj oj oj r-j 


CD O OO CD 
CD CD CD CD 
OJ OJ OJ OJ 


o 

o 

cn 


O' 

cn 


n ^ in co o 

O O' O' O' O' 

cn cn n cn cn 
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pm 

pm 






tt 

in 
cn 

C-J 




tt n 

r- oo 
==a- o 

—. C-J 


tt tt n n 

CD CD cn 

CD CD CD CD 
C-J C-J C-J C-J 


vr CD cn in =3 


n n u n n n n 

r-- o —• c-j cn in o o 

oo o o o oi^-cor- 

cn cn cn cn ---i 


r- cn o o 
c - j cn cn 

C-J C-J C-J 


pm 


tt tt 

n do n oo o -j 
?j in in ^ m 

C-J 


tt tt tt 

cn cn c-j cn co cn co c-j cn —• cd c-j 

—• -h =? =3 in in c-j c-j c j o ==r 


tt 

=^r ==r c-j 
c-j cn o 


-j =3 3 3 n 3 


ra ra s^r 


— c-j cn 






<i— =^r cn cn -i=i ra 

di in O ^ 55 jCi 

ra _Ci O -O jZs ra 

=3 O *3 C 




.—i .—i i—i .—i o "cn ra 

r—I r—1 r—1 r—I 1=1 CD • r-l 

ra ra ra ra i~i <~i i~i 


^ o -h c-j cn := =:• 

cn O O O O -<-i o 

Q. -rH iC .— •— 

o - 1=1 -s= -s= -e: -s= o o 


ra ra 


_0 cn cn ra 
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msize 0014 3# 8 

nsects 002c 18# 88 

punch 4b4d 25 193# 

read 4bc3 32 113 282# 

reader 4b4f 28 198# 



fiCTW u! j 








n 

co 


n 

GO O i 
in ^ th 
—• c-j C-J 


in 


it ±t 

cn co m 
od *= 3 - cn 
c-j c-j 


—• o ==j 


n n n n 
co in o o oo 

CD ^ cn in cd 

c-j c-j —« c-j 


CQ 

.X 

*S 

R 

-cx 

-cx 

o 

*X* 

R 

LQ 


C-J in CD -H O CD CD o 

=cr cn c-j n n c-j n =^r 

c-j c-j 


co o o n 
co c-j c-j m 


-o r- ra td c-j "c cn n co co n co 

Qj ra LPj ra CJJ I"--. aj p— ai ra o T? 

o jj xi ju jj ju o rajo ra ra jo 




r- ra ra o ^ 

o e- in £ ai ix 

-*-5 *o “O in -t-a o 

o o +j ra 

Hi Cl) (Li (U m (U (h 

in tn in in in in 


o ai 
in *i-i «-» «-» ai 

t= +J o o ■»-> 

ra rl o o ••—I 

e-. ra jQ jo *-• 

^ 3 3 3 3 
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Appendix C 

r A Skeletal GETSYS/PUTSYS Program 


[fUS £ 


!= 


o 

n 


00 CD 
+ + 


dl QJ QJ QJ 


O jZi j=i 


II II II II 
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j 




n) £ x 




frj • w—i ixi O 


O -C 
00 O 
O 00 

o o 
l o 

CL I 


-n —i n 


in CD m o 


ra 5C ra cz 

O •—i "O 


pip 

|5iP^ 

jiHiP 


© 

CM 

O 


n n 
n n 
O o o 

CD 00 O 
• CD 

m cm o 

o m co 
o o o 

CM CM CM 
O O O' 


o o 

O CD 


ra XI o TH CM CD in 

o o —< — — — —< 

CM CM CM CM CM CM CM 

O © O- O O O O 
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Jarriue here at end of tracK» woue to next tracK 






0218 04 inr b 5track = tracK+1 

0219 78 mom a»b 5see if 

021a fe02 cpi 2 ?last track 

021c da0802 Jc wr$trk ino> do another 






End of Appendix C 




Appendix D 
f'The MDS-800 Cold Start Loader for CP/M 2 


(HUH 






LTI ■—I CU 

in o 

o "O in «-> 


O 

O 

O 


in ra ro 
ra ^ ^ 

•rH _Cl _C| 


in .E O O 
ra CD CD O 
•h O CD CD 
-o 00 ' 


CU CU CU QJ CU CU CU 


in oi •#-» 


O jj Jj Ij 


o 

o 

o 

o 


o 

o 

o 

o 


o 

o 

o 

o 


o cd o o m 
oooooo 
O 00 00 CD CD 
O O —i —« —< 


jiHIRI 


Nn«jincDhoomo^ 
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1880 = b d o s1 equ bdose-cpmb 

0002 = ntrks equ 2 Snumber of tracks to read 

0031 = bdoss equ bdosl/128 inuwiber of sectors in dos 



n n sT itj □ I s oo oi o ' c-j n sr in m cn cn o —. c-j cn =^r m cd r- oo cn o 

c-j c-j c-j c-j c-j C'j c-j c-j n n n n n n n n n n 5? ^ ^ 55 sj in in 


D-2 
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if testing 

cnc rin on 80 

end if 



fSsmi 





n n 'C in co I s oo cn o ^ w n =3 in cd oo cn o ’H N n in cd r' oo 0 o n 
cococococococococncncncncncncncncncnoooooooooo-H-H-H 
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nunnnnnunnnnunn 

n co oo cn cn Ln c-j o —• c-j oo o 

n --i c-j c-j —< cm c-J —< c-j =o- in —i n =^r 


n n n n n n 


00 0 Ol 00 O O -H 

r-- o t- i -r-i oo oo co 

O 00 O O CO CO o 


O i—I CL, ■—I tfl 

aiuiinuiinmuii/ip 

isioooooordo3 
iTl-CiTi‘D-ri-n-n.H o Ui 
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CO 

CD 


n 

CD 


: " 'l 


r* o co cd ^ 

in OO OO vT Nf O th 


4* # 4*4*4*#:t44*4*## 

CD ->—i CD ' CD ->—i LTj n C-J CD C-J CD 

n co -h o m c-j c-j cn =^r =cr n n 


n c co 


Q 

"3 


Cl 

Cl 

O 

“^3 

R 

UJ 


cd c-j cd r- o n n jj ^ m <•- 

r- ^ ^ o o o- o r- o o r- 

o o o o co o co o o o o 

o m n o <*— o- o o o o 


<•- o cd o in o 

o o r- o ■*—• o 

<*— o o ■•—• o o 

<•- n o o m o 


jTi jIi xj OO 


O CL CL CL J= 


-o ra ai 


p jj xi qj ai oj 


ra rd in — 
p p ai t- 
m m p p 
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Appendix E 

A Skeletal Cold Start Loader 
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0073 0c inr c >sector=5ector 

0074 73 fiiov a>c 





lend of track* increment to next track 


+ o 

t -1 

i; tn qj 


II o +-9 

fr-i £Z O 

o ir rd o 

+-> o _o 

o ra c-i 

cu s- o <•— 
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Appendix F 

CP/M Disk Definition Library 


This listing has been printed broadside on the page, so that you can easily read the 
entire listing. 


Hi QJ ♦ 
=:• -O 


»—i 


tn ra “C 


cn 

r- 

cn 


• •- 


o 

C-J 


-i ra r- 


•-< in 
>c o cn 
o ra cn 
dq a_ cn 


in in in 


* in -o 

♦ T 3 QJ 



—i r-J n ^ ifj cn I s - cd cn o r-j n in m h- m cn o r-j 
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in 

ra 


o 

2*1 

o 

•—I ra 


"d S 
3 

o in 
3 


cd 

=^r 

C-J 


■«—i in ra 


=^T 

C-J 

O 


IU r—I «/l ^ 1/1 


CD 

CD 

C-J 


3 +-> r-j jzj ai 


m ==cr o o cd -d >•< 


3 


ai ai at 

—• f3 ^ jj Jj Jj 


c- i/i ra i/i 

•H ra c ra --I 

■—i O "d "d 


•-H •-< CD 


inminminininininin 


C -d . H in 


in i/i +J 


sz c in un ^ r—I ^ 

3 “O «*— ■—i i/ijj*d*d 


in i/i i—i 


n in cd r-. cd cn o — c-j 

CM CM C-J CM CM C-J CM CD CD CD 


cd <=? in cd r- CD cn o • 
fDnncDCDnnD^ 


CMCD^rincor^oocno—• 
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|*P*I 





ir in qi x 

■o ui in d 

od m rg 



c-j n sr in m h- cd hi o —• r^n^mcor-cocn o —« r-j n in ts 
in itj in ifj in in in in □ 0 cd cd to 0 cd cd cd □ I s - I s - I s - I s - h- 
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77: dsKhdr ZdsKnxt 

78:dsKnxt set dsKnxc+1 

79: endm 

80: endw 







82:d pbhd r macro dn 

83:dpb&dn equ $ SdisK parm block 

84: endm 




OJ CU Ol 


S= 

ai 

E 




ra in ra 


ra in ra 


in 

in 

o CD 


nJ ai 3 c 


nJ^^DCUdjaiiDllQi <4— 
E in a. —- ui in in m i 


aj cu in in ai 
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F-4 







o —« 
o _o 




o *— 
— ai 

C- 4-> 
• •—i trj 


!= 

ai 

s 


in “o in in in in 

.—I 

o<3 od od od 


in + CO E 


£ in od 


Q. .—< in .—i in Qj “O '— 


3 3 ui 


ai ai ai 
in in in 


-o 1= —I 

£ 3 •—• 

=? o • •—I 


o .sz —• 


Qj Qj Qj Qj Qj Qj 

in xn in in in «-i 


+ ii \ 


H Ul ^ 


3 

<*- t -1 

■■-• ai 


ai ai ai 
in in in 




-o "O "O "O 
«d «d «s od 


■ cl ■—• in .—i 


O -O jCi -O 
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cu tn 
!>’—<*- 
•r-l o 










£= Ol S r-H 

O t-> =3 '•-* 

•rl # CZ «*_ 


ffWrr^ 


==J 

CM 

O 


r-H CO 


P jQ O 


o CM 

♦■» "v. 

in r— I 

cu S ra 


CD 

in 

CM 




ra -o jzi O ■*—• 


3 

E =•— c - 

+P -rt oi 

•rH -O -C +P +P 

4- X c P (U OJ 

.-i cu cu o in in 


in in m 


-i -o 
X != 

oi cu 


‘‘i 


•«- “O 1=1 -o 
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c in c {= tu 

ai ra o 

tn c o <- c= 

cu O o 


■—• O O X 

CD HI HI C 

e -w- cn cn 


r in in -#-> 

in u*» ra ra in 

P P iD P 


■*-> O 

«-» -H «*_ «-> 3 CL 

cu ai ai ai tr ai 

in c -a in ai e- 


E E 

"O "O "O "O 

aiaiaiccccc 

inininaiajajaiai 


■^-«csin<5iintDr s ^ooaiO'i-icsicn , =3 , mcDr*'OQcno-i-icsim<5iincijr^cocoo 

OOOOOOOOO^^H^H^H^^H^H^H^^HC\ICMC\ICMCMCMCMCMC-JC\im 

NNNNNNNNNNNNNNNCMNNNNNNNNNNNNNN 
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pSSSl 


n* 

2 


od 
•—« ns 


U1 "O "O 
-i£ >-5 S^c 
in *• *• 

-.-i => i> 


eu T? in 


n c tr (r JJ u 

in ai ai ai tzi ai 


*Ri 

R 

o 

“RS 

R 

UJ 


f ’^-V 


-(Nn^inLDhcocno^Nn^iriiiihcom 
nnnnnnnnn<=T«=T>=T , =T , =T'a- , =T < =T^3-«^ 
N N N N N (M tM CN N N N N N CM N N CM N N 
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Appendix G 

Blocking and Deblocking Algorithms 


pswi 


This listing has been printed broadside on the page, so that you can easily read the 
entire listing. 


I 


o 

c -1 


•—i f— li¬ 


ra O r-J CD CD O 
HO-— in in o 


ai ai C2 j in m ai 




n n in cd co cn o 
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cp/m to host disk constants 


00 in jZi .o J=I 

^ C-J <-><-> +> 

O • O in in in in 
C-J in M £ £ £ X 


o o o n 

o o —• o in o 

co c-j o o o* o 


cu f- ra 

«-> o o 

ra *-> o 

Q Q .—i 

o ai • 
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II 



ai 

in 


CJD CD 
C-J C-J 
CD m 


cn 

o 

r- 

o 



-1=1 CM ra 
CD — CD 

nj r>. C-J C-J 
CD -•=. o CD 

OO Jj O <K 


cn 

o 

C-J 


o 



n ==3- oo 



— c j n ^ ici to r- m cn 
in in in in in in in in in 


n n sT io 0 r- oo cn o 

rn rn rn rn rn rn rn r_n 


—• cm n -j in 0 r- 

r-. r--- r-- r-. r-- r-. r-. 


CD 

r-' 


cn o —• 

r- CD CD 
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CLl 

U1 II 
rd ■—i 


■Ol _|Z| O x: 


■O Tl TJ -D TJ -n 


ra ra ra ra x ra cu 


o 

o 

O 


CD 

CD 

CD 

CD 


CD 

CD 



O 

CD 

CM 

CD 




CD 

CM 

CD 

cm 

CM 

CM 

CM 



o 



CD 

CD 

CM 

O 




r-. 

CD 

o 

+ 

+ 

+ 

+ 















ra 

jCt 

o 

-o 

Of 


CM 



CD 


in 

00 




CD 

ra 

"O 






CM 

CM 



CM 

CM 

CM 

CM 




CM 

CM 

CM 

o 

O 

o 

o 



O 



O' 

o 

O' 

•O 




O' 

O' 

O' 

o 

O' 

o 

o 

o 

o* 

O 



O' 

o 

o 

o 




O' 

O' 

O* 

SO- 

in 

CD 

r"- 

00 

CD 

O —' 

CM 

CD 


in 

CD 

r-- 

00 

CD 

O' 


CM 

CD 

CD 

CD 

CD 

00 

00 

00 

CD CD 

CD 

CD 

CD 

CD 

CD 

CD 

CD 

CD 

O 

o 

O 

O' 
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002f G9 mo m 1 tc 

0030 227501 shld dmaadr 

0033 c9 ret 



r- 

— 



O O O O O 

o —. cd c-j c-j =3- co 
to o o -o 

•v- C-J QJ C-J C-J CD C-J CD 

ra n n n n n n o 

I s - CD Jj "D o n ITj 00 

nnnnsr?:??^ 
o o o o o o o o 


pm 


—« c-j n ^ in cd co cn © —• c-j cd =ct in co r- co cn o —« c-j cd in cd r- oo 

c ..j c j C-J C-J C-J C-J C-J C-J C-J C-J CD CD CD CD CD CD CD CD CD 




the write entry point takes the place of 
the previous bios definition for write* 





iwrite the selected cp/w sector 





mm 









m ==r c-j *- 

r- r- o cd 

■v- c-j cn cj m c j 

H3 Cl P- Cl -V- O 


O' o -^-1 -o C-J OJ =^T O' 

—'COCOCOCQCQCOP- 
Oi C-.J rd c-.J rd C-.J rd CJ 

co ci cj ro c- j c-j cn ci 


o ai o t—• 

CO rd CD CO mtmm . 

rd P- rd -D c-.J rd 

C -o o CD CD CD 


-o o <i- O- CJ O* 00 rd -o O' CO CO CD o <t— C--J CJ CD P- rd 

g- g- in in in in in in eg id eg go go cd c - p- c- c- c- 


c-j n^intDPDooio 


c- j cj ^ in co c od cn o 


c- j n in 0 h co m 


DC^^vf^^J^vI^^irjilCJiniOlfJIClICilftininCDCDtDtDtD CD CD CD CD CD 










Ifnatch found > mark as unnecessary read 





ra cli ui in ra 


o ra ra 
x in 


ra ra ra CL ra 


ra n n n 


ra ra _o jCi 

o o o o 


<♦- C-J ra 


CD I"- ra 

JJ Jj Jj 

o o o 

O O O 


p- <*- p- «*- 


jj jj jj 


CD 

CO 

c-j 

co 


o 

o 

o 


o ■_• o o o 


■^i-N n in lq oo □ o c-j n a itj cd oo cn o -rH cj n vr in 0 co 

O O O O O O O O O •—* • •—* « •*—* • •—* C J C J C-J C J C-J C-J C-J C-J C-J 

C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J C-J 
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in D rd 


oi in at 


O O 

oi in 

o in £ 

♦j o ra 

oi cu — 

ra in in ■—i 


f®®*' r ’ 


JSZ -C "O 


ra ra ra ra IM ra ra 


■h d. a a 


—« fa e s 


qj ra i_ ra ra n3 ra ra ra 




O O O' O' o O' O O O' 

—• in CM CD CD 00 CM O' -o 

CD CD CD CD CD CD CD CD 

ra CM ra CM ra N n) I s ^ v- eg 

cd n eg n n n n jj o m cd 

e g in oo -o oj -h =^r r- cd -iti o 

<t- «t- «t- <t- <t- O' O' O' O O' O' 

OOO'OO-H-H—l-H-H-H 

O O O O O O O' O' O O' O' 


s- n ^ in 


O' O' O' O' 


CD CD CD CD CD CD CD 

CM CM CM C-g CM CM CM 

+ + + + + + + 

CD CD ra -o 0-0 


O' O O' O' O' O' O' 


tSiSt 4 ^ 




DO’-'Nn ! girjCDr s cocnO’-i eg CD^incDr-oocDO-H eg n st in cd co m 

incocococococococococor^r^r^r^r^r^r^r^r^r^mGOGOGOGOGOGommm 

CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM 
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o r-j n in cd r-- cd cn o —' r-j n in cd r- oo cn —i r- j n =^r in cd oo 

OT OT CD CD cn CD CJD CD CD CD O O O O O O- O O O O •<-* •—* —' »-« - r -> -^h ^ 

NNNNNNNNNNnnnnnnnnnnnnnnnnnnn 







clear host buffer for director/ write 


jZ. c- ^ 

CU -> 
3 E 
o ra ai 


tn o jc 3 <u 


tD N IT) IT) »—I IT) 


ca in r^ 

«v- c-j -o m cn 
r«j n o m o 
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0161 sekdsK: ds 1 Iseek disk number 

0162 sektrk: ds 2 5seek track number 

0164 seksec: ds 1 5seek sector number 









0165 hstdsK: ds 1 5host disk number 

016G hsttrk: ds 2 5host track number 

01G8 hstsec: ds 1 5host sector number 
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address: Number representing the location of a byte in memory. Within CP/M there 
are two kinds of addresses: logical and physical. A physical address refers to an abso¬ 
lute and unique location within the computer’s memory space. A logical address refers 
to the offset or displacement of a byte in relation to a base location. A standard CP/M 
program is loaded at address 0100H, the base value; the first instruction of a program 
has a physical address of 0100H and a relative address or offset of OH. 

allocation vector (ALV): An allocation vector is maintained in the BIOS for each 
logged-in disk drive. A vector consists of a string of bits, one for each block on the 
drive. The bit corresponding to a particular block is set to one when the block has been 
allocated and to zero otherwise. The first two bytes of this vector are initialized with the 
bytes ALO and AL1 on, thus allocating the directory blocks. CP/M Function 27 returns 
the allocation vector address. 

ALO, AL1: Two bytes in the disk parameter block that reserve data blocks for the 
directory. These two bytes are copied into the first two bytes of the allocation vector 
when a drive is logged in. See allocation vector. 

ALV: See allocation vector. 

ambiguous filename: Filename that contains either of the CP/M wildcard characters, 
? or *, in the primary filename, filetype, or both. When you replace characters in a 
filename with these wildcard characters, you create an ambiguous filename and can 
easily reference more than one CP/M file in a single command line. 

American Standard Code for Information Interchange: See ASCII. 

applications program: Program designed to solve a specific problem. Typical applica¬ 
tions programs are business accounting packages, word processing (editing) programs 
and mailing list programs. 

archive attribute: File attribute controlled by the high-order bit of the t3 byte 
(FCB -I-11) in a directory element. This attribute is set if the file has been archived. 

argument: Symbol, usually a letter, indicating a place into which you can substitute a 
number, letter, or name to give an appropriate meaning to the formula in question. 
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ASCII: American Standard Code for Information Interchange. ASCII is a standard 

set of seven-bit numeric character codes used to represent characters in memory. Each 
character requires one byte of memory with the high-order bit usually set to zero. 
Characters can be numbers, letters, and symbols. An ASCII file can be intelligibly 
displayed on the video screen or printed on paper. 

assembler: Program that translates assembly language into the binary machine code. 

Assembly language is simply a set of mnemonics used to designate the instruction set of 
the CPU. See ASM in Section 3 of this manual. 

back-up: Copy of a disk or file made for safekeeping, or the creation of the duplicate 
disk or file. 

Basic Disk Operating System: See BDOS. 

BDOS: Basic Disk Operating System. The BDOS module of the CP/M operating 

system provides an interface for a user program to the operating system. This interface 
is in the form of a set of function calls which may be made to the BDOS through calls to 
location 0005H in page zero. The user program specifies the number of the desired 
function in register C. User programs running under CP/M should use BDOS functions 
for all I/O operations to remain compatible with other CP/M systems and future 
releases. The BDOS normally resides in high memory directly below the BIOS. 

bias: Address value which when added to the origin address of your BIOS module 

produces 1F80H, the address of the BIOS module in the MOVCPM image. There is 
also a bias value that when added to the BOOT module origin produces 0900H, the 
address of the BOOT module in the MOVCPM image. You must use these bias values 
with the R command under DDT or SID™ when you patch a CP/M systpm. If you do 
not, the patched system may fail to function. 

binary: Base 2 numbering system. A binary digit can have one of two values: 0 or 1. 

Binary numbers are used in computers because the hardware can most easily exhibit 
two states: off and on. Generally, a bit in memory represents one binary digit. 

Basic Input/Output System: See BIOS. 

BIOS: Basic Input/Output System. The BIOS is the only hardware-dependent module 
of the CP/M system. It provides the BDOS with a set of primitive I/O operations. The 
BIOS is an assembly language module usually written by the user, hardware manufac¬ 
turer, or independent software vendor, and is the key to CP/M’s portability. The BIOS 
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interfaces the CP/M system to its hardware environment through a standardized jump 
table at the front of the BIOS routine and through a set of disk parameter tables which 
define the disk environment. Thus, the BIOS provides CP/M with a completely table- 
driven I/O system. 

BIOS base: Lowest address of the BIOS module in memory, that by definition must 
be the first entry point in the BIOS jump table. 

bit: Switch in memory that can be set to on (1) or off (0). Bits are grouped into bytes, 
eight bits to a byte, which is the smallest directly addressable unit in an Intel 8080 or 
Zilog Z80. By common convention, the bits in a byte are numbered from right, 0 for 
the low-order bit, to left, 7 for the high-order bit. Bit values are often represented in 
hexadecimal notation by grouping the bits from the low-order bit in groups of four. 
Each group of four bits can have a value from 0 to 15 and thus can easily be represented 
by one hexadecimal digit. 

BLM: See block mask. 

block: Basic unit of disk space allocation. Each disk drive has a fixed block size (BLS) 
defined in its disk parameter block in the BIOS. A block can consist of IK, 2K, 4K, 8K, 
or 16K consecutive bytes. Blocks are numbered relative to zero so that each block is 
unique and has a byte displacement in a file equal to the block number times the block 
size. 

block mask (BLM): Byte value in the disk parameter block at DPB + 3. The block 
mask is always one less than the number of 128 byte sectors that are in one block. Note 
that BLM = (2 * * BSH) - 1. 

block shift (BSH): Byte parameter in the disk parameter block at DPB + 2. Block 
shift and block mask (BLM) values are determined by the block size (BLS). Note that 
BLM = (2 ** BSH) - 1. 

blocking & deblocking algorithm: In some disk subsystems the disk sector size is 
larger than 128 bytes, usually 256, 512, 1024, or 2048 bytes. When the host sector size 
is larger than 128 bytes, host sectors must be buffered in memory and the 128-byte 
CP/M sectors must be blocked and deblocked by adding an additional module, the 
blocking and deblocking algorithm, between the BIOS disk I/O routines and the actual 
disk I/O. The host sector size must be an even multiple of 128 bytes for the algorithm to 
work correctly. The blocking and deblocking algorithm allows the BDOS and BIOS to 
function exactly as if the entire disk consisted only of 128-byte sectors, as in the 
standard CP/M installation. 
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BLS: Block size in bytes. See block. 


boot: Process of loading an operating system into memory. A boot program is a 

small piece of code that is automatically executed when you power-up or reset your 
computer. The boot program loads the rest of the operating system into memory in a 
manner similar to a person pulling himself up by his own bootstraps. This process is 
sometimes called a cold boot or cold start. Bootstrap pocedures vary from system to 
system. The boot program must be customized for the memory size and hardware 
environment that the operating system manages. Typically, the boot resides on the first 
sector of the system tracks on your system disk. When executed, the boot loads the 
remaining sectors of the system tracks into high memory at the location for which the 
CP/M system has been configured. Finally, the boot transfers execution to the boot 
entry point in the BIOS jump table so that the system can initialize itself. In this case, 
the boot program should be placed at 900H in the SYSGEN image. Alternatively, the 
boot program may be located in ROM. 




bootstrap: See boot. 


BSH: See block shift. 


BTREE: General purpose file access method that has become the standard organiza¬ 

tion for indexes in large data base systems. BTREE provides near optimum perform¬ 
ance over the full range of file operations, such as insertion, deletion, search, and search 
next. 


buffer: Area of memory that temporarily stores data during the transfer of informa- 

tion. 


built-in commands: Commands that permanently reside in memory. They respond 
quickly because they are not accessed from a disk. 

byte: Unit of memory or disk storage containing eight bits. A byte can represent a 

binary number between 0 and 255, and is the smallest unit of memory that can be 
addressed directly in 8-bit CPUs such as the Intel 8080 or Zilog Z80. 

CCP: Console Command Processor. The CCP is a module of the CP/M operating 

system. It is loaded directly below the BDOS module and interprets and executes 
commands typed by the console user. Usually these commands are programs that the 
CCP loads and calls. Upon completion, a command program may return control to the 
CCP if it has not overwritten it. If it has, the program can reload the CCP into memory 
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by a warm boot operation initiated by either a jump to zero, BDOS system reset 
(Function 0), or a cold boot. Except for its location in high memory, the CCP works 
like any other standard CP/M program; that is, it makes only BDOS function calls for 
its I/O operations. 

CCP base: Lowest address of the CCP module in memory. This term sometimes 
refers to the base of the CP/M system in memory, as the CCP is normally the lowest 
CP/M module in high memory. 

checksum vector (CSV): Contiguous data area in the BIOS, with one byte for each 
directory sector to be checked, that is, CKS bytes. See CKS. A checksum vector is 
initialized and maintained for each logged-in drive. Each directory access by the system 
results in a checksum calculation that is compared with the one in the checksum vector. 
If there is a discrepancy, the drive is set to Read-Only status. This feature prevents the 
user from inadvertently switching disks without logging in the new disk. If the new disk 
is not logged-in, it is treated the same as the old one, and data on it might be destroyed 
if writing is done. 

CKS: Number of directory records to be checked summed on directory accesses. This 
is a parameter in the disk parameter block located in the BIOS. If the value of CKS is 
zero, then no directory records are checked. CKS is also a parameter in the diskdef 
macro library, where it is the actual number of directory elements to be checked rather 
than the number of directory records. 

cold boot: See boot. Cold boot also refers to a jump to the boot entry, point in the 
BIOS jump table. 

COM: Filetype for a CP/M command file. See command file. 

command: CP/M command line. In general, a CP/M command line has three parts: 

the command keyword, command tail, and a carriage return. To execute a command, 
enter a CP/M command line directly after the CP/M prompt at the console and press 
the carriage return or enter key. 

command file: Executable program file of filetype COM. A command file is a 
machine language object module ready to be loaded and executed at the absolute 
address of 0100H. To execute a command file, enter its primary filename as the 
command keyword in a CP/M command line. 

command keyword: Name that identifies a CP/M command, usually the primary 
filename of a file of type COM, or a built-in command. The command keyword 
precedes the command tail and the carriage return in the command line. 
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command syntax: Statement that defines the correct way to enter a command. The 
correct structure generally includes the command keyword, the command tail, and a 
carriage return. A syntax line usually contains symbols that you should replace with 
actual values when you enter the command. 

command tail: Part of a command that follows the command keyword in the com¬ 
mand line. The command tail can include a drive specification, a filename and filetype, 
and options or parameters. Some commands do not require a command tail. 

CON: Mnemonic that represents the CP/M console device. For example, the CP/M 

command PIP CON: =TEST.SUB displays the file TEST.SUB on the console device. 
The explanation of the STAT command tells how to assign the logical device CON: to 
various physical devices. See console. 

concatenate: Name of the PIP operation that copies two or more separate files into 

one new file in the specified sequence. 

concurrency: Execution of two processes or operations simultaneously. 

CONIN: BIOS entry point to a routine that reads a character from the console 

device. 

CONOUT: BIOS entry point to a routine that sends a character to the console 

device. 

console: Primary input/output device. The console consists of a listing device, such as 
a screen or teletype, and a keyboard through which the user communicates with the 
operating system or applications program. 

Console Command Processor: See CCP. 

CONST: BIOS entry point to a routine that returns the status of the console device. 

control character: Nonprinting character combination. CP/M interprets some con¬ 
trol characters as simple commands such as line editing functions. To enter a control 
character, hold down the CONTROL key and strike the specified character key. 

Control Program for Microcomputers: See CP/M. 

CP/M: Control Program for Microcomputers. An operating system that manages 

computer resources and provides a standard systems interface to software written for a 
large variety of microprocessor-based computer systems. 
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CP/M 1.4 compatibility: For a CP/M 2 system to be able to read correctly single¬ 
density disks produced under a CP/M 1.4 system, the extent mask must be zero and the 
block size IK. This is because under CP/M 2 an FCB may contain more than one 
extent. The number of extents that may be contained by an FCB is EXM + 1. The issue 
of CP/M 1.4 compatibility also concerns random file I/O. To perform random file I/O 
under CP/M 1.4, you must maintain an FCB for each extent of the file. This scheme is 
upward compatible with CP/M 2 for files not exceeding 512K bytes, the largest file size 
supported under CP/M 1.4. If you wish to implement random I/O for files larger than 
512K bytes under CP/M 2, you must use the random read and random write functions, 
BDOS functions 33, 34, and 36. In this case, only one FCB is used, and if CP/M 1.4 
compatiblity is required, the program must use the return version number function, 
BDOS Function 12, to determine which method to employ. 

CP/M prompt: Characters that indicate that CP/M is ready to execute your next 
command. The CP/M prompt consists of an upper-case letter, A—P, followed by a > 
character; for example, A>. The letter designates which drive is currently logged in as 
the default drive. CP/M will search this drive for the command file specified, unless the 
command is a built-in command or prefaced by a select drive command: for example, 
B:STAT. 

CP/NET: Digital Research network operating system enabling microcomputers to 

obtain access to common resources via a network. CP/NET consists of MP/M masters 
and CP/M slaves with a network interface between them. 

CSV: See checksum vector. 

cursor: One-character symbol that can appear anywhere on the console screen. The 

cursor indicates the position where the next keystroke at the console will have an effect. 

data file: File containing information that will be processed by a program. 

deblocking: See blocking 5c deblocking algorithm. 

default: Currently selected disk drive and user number. Any command that does not 

specify a disk drive or a user number references the default disk drive and user number. 
When CP/M is first invoked, the default disk drive is drive A, and the default user 
number is 0. 
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default buffer: Default 128-byte buffer maintained at 0080H in page zero. When the 
CCP loads a COM file, this buffer is initialized to the command tail; that is, any 
characters typed after the COM file name are loaded into the buffer. The first byte at 
0080H contains the length of the command tail, while the command tail itself begins at 
0081H. The command tail is terminated by a byte containing a binary zero value. The I 
command under DDT and SID initializes this buffer in the same way as the CCP. 

default FCB: Two default FCBs are maintained by the CCP at 005CH and 006CH in 
page zero. The first default FCB is initialized from the first delimited field in the 
command tail. The second default FCB is initialized from the next field in the command 
tail. 

delimiter: Special characters that separate different items in a command line; for 

example, a colon separates the drive specification from the filename. The CCP recog¬ 
nizes the following characters as delimiters: . : = ; < > _, blank, and carriage 

return. Several CP/M commands also treat the following as delimiter characters: , [ ] 
( ) $. It is advisable to avoid the use of delimiter characters and lower-case characters 
in CP/M filenames. 

DIR: Parameter in the diskdef macro library that specifies the number of directory 

elements on the drive. 

DIR attribute: File attribute. A file with the DIR attribute can be displayed by a DIR 
command. The file can be accessed from the default user number and drive only. 

DIRBUF: 128-byte scratchpad area for directory operations, usually located at the 

end of the BIOS. DIRBUF is used by the BDOS during its directory operations. DIRBUF 
also refers to the two-byte address of this scratchpad buffer in the disk parameter 
header at DPbase + 8 bytes. 

directory: Portion of a disk that contains entries for each file on the disk. In response 

to the DIR command, CP/M displays the filenames stored in the directory. The direc¬ 
tory also contains the locations of the blocks allocated to the files. Each file directory 
element is in the form of a 32-byte FCB, although one file can have several elements, 
depending on its size. The maximum number of directory elements supported is spe¬ 
cified by the drive’s disk parameter block value for DRM. 

directory element: Data structure. Each file on a disk has one or more 32-byte 
directory elements associated with it. There are four directory elements per directory 
sector. Directory elements can also be referred to as directory FCBs. 
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directory entry: File entry displayed by the DIR command. Sometimes this term 
refers to a physical directory element. 

disk, diskette: Magnetic media used for mass storage in a computer system. Pro¬ 
grams and data are recorded on the disk in the same way music can be recorded on 
cassette tape. The CP/M operating system must be initially loaded from disk when the 
computer is turned on. Diskette refers to smaller capacity removable floppy diskettes, 
while disk may refer to either a diskette, removable cartridge disk, or fixed hard disk. 
Hard disk capacities range from five to several hundred megabytes of storage. 




diskdef macro library: Library of code that when used with MAC, the Digital Re¬ 
search macro assembler, creates disk definition tables such as the DPB and DPH 
automatically. 


disk drive: Peripheral device that reads and writes information on disk. CP/M assigns 
a letter to each drive under its control. For example, CP/M may refer to the drives in a 
~ four-drive system as A, B, C, and D. 


disk parameter block (DPB): Data structure referenced by one or more disk para¬ 
meter headers. The disk parameter block defines disk characteristics in the fields listed 
below: 





SPT is the total number of sectors per track. 

BSH is the data allocation block shift factor. 

BLM is the data allocation block mask. 

EXM is the extent mask determined by BLS and DSM. 
DSM is the maximum data block number. 

DRM is the maximum number of directory entries—1. 
ALO reserves directory blocks. 

AL1 reserves directory blocks. 

CKS is the number of directory sectors check summed. 
OFF is the number of reserved system tracks. 



i 


The address of the disk parameter block is located in the disk parameter header at 
DPbase + 0AH. CP/M Function 31 returns the DPB address. Drives with the same 
characteristics can use the same disk parameter header, and thus the same DPB. 
However, drives with different characteristics must each have their own disk parameter 
header and disk parameter blocks. When the BDOS calls the SELDSK entry point in the 
BIOS, SELDSK must return the address of the drive’s disk parameter header in register 
HL. 
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disk parameter header (DPH): Data structure that contains information about the 
disk drive and provides a scratchpad area for certain BDOS operations. The disk 
parameter header contains six bytes of scratchpad area for the BDOS, and the follow- 
ing five 2-byte parameters: 

XLT is the sector translation table address. 

DIRBUF is the directory buffer address. 

DPB is the disk parameter block address. 

CSV is the checksum vector address. 

ALV is the allocation vector address. 


Given n disk drives, the disk parameter headers are arranged in a table whose first row 
of 16 bytes corresponds to drive 0, with the last row corresponding to drive n — 1. 

DKS: Parameter in the diskdef macro library specifying the number of data blocks on 
the drive. 

DMA: Direct Memory Access. DMA is a method of transferring data from the disk 

into memory directly. In a CP/M system, the BDOS calls the BIOS entry point READ to 
read a sector from the disk into the currently selected DMA address. The DMA address 
must be the address of a 128-byte buffer in memory, either the default buffer at 0080H 
in page zero, or a user-assigned buffer in the TPA. Similarly, the BDOS calls the BIOS 
entry point WRITE to write the record at the current DMA address to the disk. 


DN: Parameter in the diskdef macro library specifying the logical drive number. ^ ^ 

DPB: See disk parameter block. 

DPH: See disk parameter header. *“1 

DRM: 2-byte parameter in the disk parameter block at DPB -I- 7. DRM is one less 
than the total number of directory entries allowed for the drive. This value is related to 
DPB bytes ALO and AL1, which allocates up to 16 blocks for directory entries. 


DSM: 2-byte parameter of the disk parameter block at DPB -I- 5. DSM is the 

maximum data block number supported by the drive. The product BLS times 
(DSM -1-1) is the total number of bytes held by the drive. This must not exceed the 
capacity of the physical disk less the reserved system tracks. 

editor: Utility program that creates and modifies text files. An editor can be used for 
creation of documents or creation of code for computer programs. The CP/M editor is 
invoked by typing the command ED next to the system prompt on the console. **1 

-—-- m DIGITAL RESEARCH" 




H-10 



CP/M Operating System Manual 


H Glossary 


EX: Extent number field in an FCB. See extent. 

executable: Ready to be run by the computer. Executable code is a series of instruc¬ 

tions that can be carried out by the computer. For example, the computer cannot 
execute names and addresses, but it can execute a program that prints all those names 
and addresses on mailing labels. 

execute a program: Start the processing of executable code. 

EXM: See extent mask. 

extent: 16K consecutive bytes in a file. Extents are numbered from 0 to 31. One 

extent can contain 1, 2, 4, 8, or 16 blocks. EX is the extent number field of an FCB and 
is a one-byte field at FCB +12, where FCB labels the first byte in the FCB. Depending 
on the block size (BLS) and the maximum data block number (DSM), an FCB can 
contain 1, 2, 4, 8, or 16 extents. The EX field is normally set to 0 by the user but 
contains the current extent number during file I/O. The term FCB folding describes 
FCBs containing more than one extent. In CP/M version 1.4, each FCB contained only 
one extent. Users attempting to perform random record I/O and maintain CP/M 1.4 
compatiblity should be aware of the implications of this difference. See CP/M 1.4 
compatibility. 

extent mask (EXM): A byte parameter in the disk parameter block located at DPB + 
3. The value of EXM is determined by the block size (BLS) and whether the maximum 
data block number (DSM) exceeds 255. There are EXM + 1 extents per directory FCB. 

FCB: See File Control Block. 

file: Collection of characters, instructions, or data that can be referenced by a unique 
identifier. Files are usually stored on various types of media, such as disk, or magnetic 
tape. A CP/M file is identified by a file specification and resides on disk as a collection of 
from zero to 65,536 records. Each record is 128 bytes and can contain either binary or 
ASCII data. Binary files contain bytes of data that can vary in value from OH to OFFH. 
ASCII files contain sequences of character codes delineated by a carriage return and 
line-feed combination; normally byte values range from OH to 7FH. The directory 
maps the file as a series of physical blocks. Although files are defined as a sequence of 
consecutive logical records, these records can not reside in consecutive sectors on the 
disk. See also block, directory, extent, record, and sector. 
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File Control Block (FCB): Structure used for accessing files on disk. Contains the 
drive, filename, filetype, and other information describing a file to be accessed or 
created on the disk. A file control block consists of 36 consecutive bytes specified by the 
user for file I/O functions. FCB can also refer to a directory element in the directory 
portion of the allocated disk space. These contain the same first 32 bytes of the FCB, 
but lack the current record and random record number bytes. 

filename: Name assigned to a file. A filename can include a primary filename of one 

to eight characters; a filetype of zero to three characters. A period separates the primary 
filename from the filetype. 


file specification: Unique file identifier. A complete CP/M file specification includes a mm; 
disk drive specification followed by a colon, d:, a primary filename of one to eight 
characters, a period, and a filetype of zero to three characters. For example, b:exam- 
ple.tex is a complete CP/M file specification. ,, 

filetype: Extension to a filename. A filetype can be from zero to three characters and 
must be separated from the primary filename by a period. A filetype can tell something 
about the file. Some programs require that files to be processed have specific filetypes. 


floppy disk: Flexible magnetic disk used to store information. Floppy disks come in 
5 1/4- and 8-inch diameters. 


FSC: Parameter in the diskdef macro library specifying the first physical sector 

number. This parameter is used to determine SPT and build XLT. 


hard disk: Rigid, platter-like, magnetic disk sealed in a container. A hard disk stores 
more information than a floppy disk. . 

hardware: Physical components of a computer. 

hexadecimal notation: Notation for base 16 values using the decimal digits and 
letters A, B, C, D, E, and F to represent the 16 digits. Hexadecimal notation is often 
used to refer to binary numbers. A binary number can be easily expressed as a hexade¬ 
cimal value by taking the bits in groups of 4, starting with the least significant bit, and Mf 
expressing each group as a hexadecimal digit, 0-F. Thus the bit value 1011 becomes 
OBH and 10110101 becomes 0B5H. 

hex file: ASCII-printable representation of a command, machine language, file. 
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hex file format: Absolute output of ASM and MAC for the Intel 8080 is a hex format 
file, containing a sequence of absolute records that give a load address and byte values 
to be stored, starting at the load address. 

HOME: BIOS entry point which sets the disk head of the currently selected drive to 
the track zero position. 

host: Physical characteristics of a hard disk drive in a system using the blocking and 
deblocking algorithm. The term, host, helps distinguish physical hardware characteris¬ 
tics from CP/M’s logical characteristics. For example, CP/M sectors are always 128 
bytes, although the host sector size can be a multiple of 128 bytes. 

input: Data going into the computer, usually from an operator typing at the terminal 
or by a program reading from the disk. 

input/output: See I/O. 

interface: Object that allows two independent systems to communicate with each 

other, as an interface between hardware and software in a microcomputer. 

I/O: Abbreviation for input/output. Usually refers to input/output operations or 

routines handling the input and output of data in the computer system. 

IOBYTE: A one-byte field in page zero, currently at location 0003H, that can 

support a logical-to-physical device mapping for I/O. However, its implementation in 
your BIOS is purely optional and might or might not be supported in a given CP/M 
system. The IOBYTE is easily set using the command: 

STAT <logical device> = <physical device> 

The CP/M logical devices are CON:, RDR:, PUN:, and LST:; each of these can be 
assigned to one of four physical devices. The IOBYTE can be initialized by the BOOT 
entry point of the BIOS and interpreted by the BIOS I/O entry points CONST, CONIN, 
CONOUT, LIST, PUNCH, and READER. Depending on the setting of the IOBYTE, 
different I/O drivers can be selected by the BIOS. For example, setting LST: = TTY: 
might cause LIST output to be directed to a serial port, while setting LST: = LPT: 
causes LIST output to be directed to a parallel port. 

K: Abbreviation for kilobyte. See kilobyte. 
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keyword: See command keyword. 

kilobyte (K): 1024 bytes or 0400H bytes of memory. This is a standard unit of 

memory. For example, the Intel 8080 supports up to 64K of memory address space or 
65,536 bytes. 1024 kilobytes equal one megabyte, or over one million bytes. 

linker: Utility program used to combine relocatable object modules into an absolute 

file ready for execution. For example, LINK-80™ creates either a COM or PRL file 
from relocatable REL files, such as those produced by PL/I-80™. 

LIST: A BIOS entry point to a routine that sends a character to the list device, usually 
a printer. 

list device: Device such as a printer onto which data can be listed or printed. 

LISTST: BIOS entry point to a routine that returns the ready status of the list device. 

loader: Utility program that brings an absolute program image into memory ready 

for execution under the operating system, or a utility used to make such an image. For 
example, LOAD prepares an absolute COM file from the assembler hex file output that 
is ready to be executed under CP/M. 

logged in: Made known to the operating system, in reference to drives. A drive is 
logged in when it is selected by the user or an executing process. It remains selected or 
logged in until you change disks in a floppy disk drive or enter CTRL-C at the com¬ 
mand level, or until a BDOS Function 0 is executed. 

logical: Representation of something that might or might not be the same in its actual 

physical form. For example, a hard disk can occupy one physical drive, yet you can 
divide the available storage on it to appear to the user as if it were in several different 
drives. These apparent drives are the logical drives. 

logical sector: See sector. 

logical-to-physical sector translation table: See XLT. 

LSC: Diskdef macro library parameter specifying the last physical sector number. 
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LST: Logical CP/M list device, usually a printer. The CP/M list device is an output- 
only device referenced through the LIST and LISTST entry points of the BIOS. The 
STAT command allows assignment of LST: to one of the physical devices: TTY:, 
CRT:, LPT:, or UL1:, provided these devices and the IOBYTE are implemented in the 
LIST and LISTST entry points of your CP/M BIOS module. The CP/NET command 
NETWORK allows assignment of LST: to a list device on a network master. For 
example, PIP LST: =TEST.SUB prints the file TEST.SUB on the list device. 

macro assembler: Assembler code translator providing macro processing facilities. 
Macro definitions allow groups of instructions to be stored and substituted in the 
source program as the macro names are encountered. Definitions and invocations can 
be nested and macro parameters can be formed to pass arbitrary strings of text to a 
specific macro for substitution during expansion. 

megabyte: Over one million bytes; 1024 kilobytes. See byte, and kilobyte. 

microprocessor: Silicon chip that is the central processing unit (CPU) of the micro¬ 

computer. The Intel 8080 and the Zilog Z80 are microprocessors commonly used in 
CP/M systems. 

MOVCPM image: Memory image of the CP/M system created by MOVCPM. This 
image can be saved as a disk file using the SAVE command or placed on the system 
tracks using the SYSGEN command without specifying a source drive. This image 
varies, depending on the presence of a one-sector or two-sector boot. If the boot is less 
than 128 bytes (one sector), the boot begins at 0900H, the CP/M system at 0980H, and 
the BIOS at 1F80H. Otherwise, the boot is at 0900H, the CP/M system at 1000H, and 
the BIOS at 2000H. In a CP/M 1.4 system with a one-sector boot, the addresses are the 
same as for the CP/M 2 system—except that the BIOS begins at 1E80H instead of 
1F80H. 

MP/M: Multi-Programming Monitor control program. A microcomputer operating 
system supporting multi-terminal access with multi-programming at each terminal. 

multi-programming: The capability of initiating and executing more than one pro¬ 

gram at a time. These programs, usually called processes, are time-shared, each receiv¬ 
ing a slice of CPU time on a round-robin basis. See concurrency. 

nibble: One half of a byte, usually the high-order or low-order 4 bits in a byte. 

OFF: Two-byte parameter in the disk parameter block at DPB + 13 bytes. This 

value specifies the number of reserved system tracks. The disk directory begins in the 
first sector of track OFF. 
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OFS: Diskdef macro library parameter specifying the number of reserved system 

tracks. See OFF. 

operating system: Collection of programs that supervises the execution of other 
programs and the management of computer resources. An operating system provides 
an orderly input/output environment between the computer and its peripheral devices. 
It enables user-written programs to execute safely. An operating system standardizes 
the use of computer resources for the programs running under it. 

option: One of many parameters that can be part of a command tail. Use options to 
specify additional conditions for a command’s execution. 

output: Data that is sent to the console, disk, or printer. 

page: 256 consecutive bytes in memory beginning on a page boundary, whose base 

address is a multiple of 256 (100H) bytes. In hex notation, pages always begin at an 
address with a least significant byte of zero. 

page relocatable program: See PRL. 

page zero: Mertiory region between 0000H and 0100H used to hold critical system 
parameters. Page zero functions primarily as an interface region between user programs 
and the CP/M BDOS module. Note that in non-standard systems this region is the base 
page of the system and represents the first 256 bytes of memory used by the CP/M 
system and user programs running under it. 

parameter: Value in the command tail that provides additional information for the 

command. Technically, a parameter is a required element of a command. 

peripheral devices: Devices external to the CPU. For example, terminals, printers, 
and disk drives are common peripheral devices that are not part of the processor but 
are used in conjunction with it. 

physical: Characteristic of computer components, generally hardware, that actually 

exist. In programs, physical components can be represented by logical components. 

primary filename: First 8 characters of a filename. The primary filename is a unique 
name that helps the user identify the file contents. A primary filename contains one to 
eight characters and can include any letter or number and some special characters. The 
primary filename follows the optional drive specification and precedes the optional 
filetype. 
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PRL: Page relocatable program. A page relocatable program is stored on disk with a 
PRL filetype. Page relocatable programs are easily relocated to any page boundary and 
thus are suitable for execution in a nonbanked MP/M system. 

program: Series of coded instructions that performs specific tasks when executed by 

a computer. A program can be written in a processor-specific language or a high-level 
language that can be implemented on a number of different processors. 

prompt: Any characters displayed on the video screen to help the user decide what 

the next appropriate action is. A system prompt is a special prompt displayed by the 
operating system. The alphabetic character indicates the default drive. Some applica¬ 
tions programs have their own special prompts. See CP/M prompt. 

PUN: Logical CP/M punch device. The punch device is an output-only device ac¬ 

cessed through the PUNCH entry point of the BIOS. In certain implementations, PUN: 
can be a serial device such as a modem. 

PUNCH: BIOS entry point to a routine that sends a character to the punch device. 

RDR: Logical CP/M reader device. The reader device is an input-only device accessed 
through the READER entry point in the BIOS. See PUN:. 

READ: Entry point in the BIOS to a routine that reads 128 bytes from the currently 
selected drive, track, and sector into the current DMA address. 

READER: Entry point to a routine in the BIOS that reads the next character from the 
currently assigned reader device. 

Read-Only (R/O): Attribute that can be assigned to a disk file or a disk drive. When 
assigned to a file, the Read-Only attribute allows you to read from that file‘but not 
write to it. When assigned to a drive, the Read-Only attribute allows you to read any 
file on the disk, but prevents you from adding a new file, erasing or changing a file, 
renaming a file, or writing on the disk. The STAT command can set a file or a drive to 
Read-Only. Every file and drive is either Read-Only or Read-Write. The default setting 
for drives and files is Read-Write, but an error in resetting the disk or changing media 
automatically sets the drive to Read-Only until the error is corrected. See also ROM. 

Read-Write (R/W): Attribute that can be assigned to a disk file or a disk drive. The 
Read-Write attribute allows you to read from and write to a specific Read-Write file or 
to any file on a disk that is in a drive set to Read-Write. A file or drive can be set to 
either Read-Only or Read-Write. 
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record: Group of bytes in a file. A physical record consists of 128 bytes and is the 

basic unit of data transfer between the operating system and the application program. 
A logical record might vary in length and is used to represent a unit of information. 
Two 64-byte employee records can be stored in one 128-byte physical record. Records 
are grouped together to form a file. 

recursive procedure: Code that can call itself during execution. 

reentrant procedure: Code that can be called by one process while another is already 
executing it. Thus, reentrant code can be shared between different users. Reentrant 
procedures must not be self-modifying; that is, they must be pure code and not contain 
data. The data for reentrant procedures can be kept in a separate data area or placed on 
the stack. 

restart (RST): One-byte call instruction usually used during interrupt sequences and 
for debugger break pointing. There are eight restart locations, RST 0 through RST 7, 
whose addresses are given by the product of 8 times the restart number. 

R/O: See Read-Only. 

ROM: Read-Only memory. This memory can be read but not written and so is 

suitable for code and preinitialized data areas only. 

RST: See restart. 

R/W: See Read-Write. 

sector: In a CP/M system, a sector is always 128 consecutive bytes. A sector is the 

basic unit of data read and written on the disk by the BIOS. A sector can be one 
128-byte record in a file or a sector of the directory. The BDOS always requests a 
logical sector number between 0 and (SPT-1). This is typically translated into a 
physical sector by the BIOS entry point SECTRAN. In some disk subsystems, the disk 
sector size is larger than 128 bytes, usually a power of two, such as 256, 512, 1024, or 
2048 bytes. These disk sectors are always referred to as host sectors in CP/M docu¬ 
mentation and should not be confused with other references to sectors, in which cases 
the CP/M 128-byte sectors should be assumed. When the host sector size is larger than 
128 bytes, host sectors must be buffered in memory and the 128-byte CP/M sectors 
must be blocked and deblocked from them. This can be done by adding an additional 
module, the blocking and deblocking algorithm, between the BIOS disk I/O routines 
and the actual disk I/O. 
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sectors per track (SPT): A two-byte parameter in the disk parameter block at DPB + 
0. The BDOS makes calls to the BIOS entry point SECTRAN with logical sector 
numbers ranging between 0 and (SPT - 1) in register BC. 

SECTRAN: Entry point to a routine in the BIOS that performs logical-to-physical 

sector translation for the BDOS. 

SELDSK: Entry point to a routine in the BIOS that sets the currently selected drive. 

SETDMA: Entry point to a routine in the BIOS that sets the currently selected DMA 

address. The DMA address is the address of a 128-byte buffer region in memory that is 
used to transfer data to and from the disk in subsequent reads and writes. 

SETSEC: Entry point to a routine in the BIOS that sets the currently selected sector. 

SETTRK: Entry point to a routine in the BIOS that sets the currently selected track. 

skew factor: Factor that defines the logical-to-physical sector number translation in 
XLT. Logical sector numbers are used by the BDOS and range between 0 and (SPT — 
1). Data is written in consecutive logical 128-byte sectors grouped in data blocks. The 
number of sectors per block is given by BLS/128. Physical sectors on the disk media are 
also numbered consecutively. If the physical sector size is also 128 bytes, a one-to-one 
relationship exists between logical and physical sectors. The logical-to-physical transla¬ 
tion table (XLT) maps this relationship, and a skew factor is typically used in generat¬ 
ing the table entries. For instance, if the skew' factor is 6, XLT will be: 

Logical: 0 1 2 3 4 5 6 ... 25 

Physical: 1 7 13 19 25 5 11 ... 22 

The skew factor allows time for program processing without missing the next sector. 
Otherwise, the system must wait for an entire disk revolution before reading the next 
logical sector. The skew factor can be varied, depending on hardware speed and 
application processing overhead. Note that no sector translation is done when the 
physical sectors are larger than 128 bytes, as sector deblocking is done in this case. See 
also sector, SKF, and XLT. 

SKF: A diskdef macro library parameter specifying the skew factor to be used in 

building XLT. If SKF is zero, no translation table is generated and the XLT byte in the 
DPH will be 0000H. 
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software: Programs that contain machine-readable instructions, as opposed to hard¬ 
ware, which is the actual physical components of a computer. 

source file: ASCII text file usually created with an editor that is an input file to a 
system program, such as a language translator or text formatter. 

SP: Stack pointer. See stack. 

spooling: Process of accumulating printer output in a file while the printer is busy. 

The file is printed when the printer becomes free; a program does not have to wait for 
the slow printing process. 

SPT: See sectors per track. 

stack: Reserved area of memory where the processor saves the return address when a 

call instruction is received. When a return instruction is encountered, the processor 
restores the current address on the stack to the program counter. Data such as the 
contents of the registers can also be saved on the stack. The push instruction places data 
on the stack and the pop instruction removes it. An item is pushed onto the stack by 
decrementing the stack pointer (SP) by 2 and writing the item at the SP address. In other 
words, the stack grows downward in memory. 

syntax: Format for entering a given command. 

SYS: See system attribute. 

SYSGEN image: Memory image of the CP/M system created by SYSGEN when a 
destination drive is not specified. This is the same as the MOVCPM image that can be 
read by SYSGEN if a source drive is not specified. See MOVCPM image. 

system attribute (SYS): File attribute. You can give a file the system attribute by using 
the SYS option in the STAT command or by using the set file attributes function, BDOS 
Function 12. A file with the SYS attribute is not displayed in response to a DIR 
command. If you give a file with user number 0 the SYS attribute, you can read and 
execute that file from any user number on the same drive. Use this feature to make your 
commonly used programs available under any user number. 

system prompt: Symbol displayed by the operating system indicating that the system 
is ready to receive input. See prompt and CP/M prompt. 


FI-20 


m DIGITAL RESEARCH 



CP/M Operating System Manual 


H Glossary 


system tracks: Tracks reserved on the disk for the CP/M system. The number of 
system tracks is specified by the parameter OFF in the disk parameter block (DPB). The 
system tracks for a drive always precede its data tracks. The command SYSGEN copies 
the CP/M system from the system tracks to memory, and vice versa. The standard 
SYSGEN utility copies 26 sectors from track 0.and 26 sectors from track 1. When the 
system tracks contain additional sectors or tracks to be copied, a customized SYSGEN 
must be used. 

terminal: See console. 

TPA: Transient Program Area. Area in memory where user programs run and store 
data. This area is a region of memory beginning at 0100H and extending to the base of 
the CP/M system in high memory. The first module of the CP/M system is the CCP, 
which can be overwritten by a user program. If so, the TPA is extended to the base of 
the CP/M BDOS module. If the CCP is overwritten, the user program must terminate 
with either a system reset (Function 0) call or a jump to location zero in page zero. The 
address of the base of the CP/M BDOS is stored in location 0006H in page zero least 
significant byte first. 

track: Data on the disk media is accessed by combination of track and sector num¬ 

bers. Tracks form concentric rings on the disk; the standard IBM single-density disks 
have 77 tracks. Each track consists of a fixed number of numbered sectors. Tracks are 
numbered from zero to one less than the number of tracks on the disk. 

Transient Program Area: See TPA. 

upward compatible: Term meaning that a program created for the previously re¬ 
leased operating system, or compiler, runs under the newly released version of the same 
operating system. 

USER: Term used in CP/M and MP/M systems to distinguish distinct regions of the 
directory. 

user number: Number assigned to files in the disk directory so that different users 
need only deal with their own files and have their own directories, even though they are 
all working from the same disk. In CP/M, files can be divided into 16 user groups. 

utility: Tool. Program that enables the user to perform certain operations, such as 

copying files, erasing files, and editing files. The utilities are created for the convenience, 
of programmers and users. 
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vector: Location in memory. An entry point into the operating system used for 

making system calls or interrupt handling. 

warm start: Program termination by a jump to the warm start vector at location 
0000H, a system reset (BDOS Function 0), or a CTRL-C typed at the keyboard. A 
warm start reinitializes the disk subsystem and returns control to the CP/M operating 
system at the CCP level. The warm start vector is simply a jump to the WBOOT entry 
point in the BIOS. 

WBOOT: Entry point to a routine in the BIOS used when a warm start occurs. A 

warm start is performed when a user program branches to location 0000H, when the 
CPU is reset from the front panel, or when the user types CTRL-C. The CCP and BDOS 
are reloaded from the system tracks of drive A. 

wildcard characters: Special characters that match certain specified items. In CP/M 
there are two wildcard characters: ? and *. The ? can be substituted for any single 
character in a filename, and the * can be substituted for the primary filename, the 
filetype, or both. By placing wildcard characters in filenames, the user creates an 
ambiguous filename and can quickly reference one or more files. 

word: 16-bit or two-byte value, such as an address value. Although the Intel 8080 is 

an 8-bit CPU, addresses occupy two bytes and are called word values. 

WRITE: Entry point to a routine in the BIOS that writes the record at the currently 

selected DMA address to the currently selected drive, track, and sector. 

XLT: Logical-to-physical sector translation table located in the BIOS. SECTRAN 

uses XLT to perform logical-to-physical sector number translation. XLT also refers to 
the two-byte address in the disk parameter header at DPBASE -I- 0. If this parameter is 
zero, no sector translation takes place. Otherwise this parameter is the address of the 
translation table. 

ZERO PAGE: See page zero. 


End of Appendix H 
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Messages come from several different sources. CP/M displays error messages when 
there are errors in calls to the Basic Disk Operating System (BDOS). CP/M also displays 
messages when there are errors in command lines. Each utility supplied with CP/M has 
its own set of messages. The following lists CP/M messages and utility messages. One 
might see messages other than those listed here if one is running an application pro¬ 
gram. Check the application program’s documentation for explanations of those mes¬ 
sages. 


Table 1-1. CP/M Error Messages 



Message 

Meaning 

jiWf 

o 




DDT. This message has four possible meanings: 

■ DDT does not understand the assembly language instruction. 

ww 


■ The file cannot be opened. 

■ A checksum error occurred in a HEX file. 

■ The assembler/disassembler was overlayed. 


ABORTED 

PIP. You stopped a PIP operation by pressing a key. 


ASM Error Messages 


D 

Data error: data statement element cannot be placed in spe- 



cified data area. 

jlSP 




E 

Expression error: expression cannot be evaluated during 



assembly. 

ism?) 



--- 

L 

Label error: label cannot appear in this context (might be 



duplicate label). 


I' 1 .ow4 


! DIGITAL RESEARCH ,v 


1-1 




I CP/M Error Messages 


CP/M Operating System Manual 


ImmM 


Table 1-1. (continued) 


Message 

Meaning 

N 

Not implemented: unimplemented features, such as macros, 
are trapped. 

□ 

Overflow: expression is too complex to evaluate. 

P 

Phase error: label value changes on two passes through 
assembly. 

R 

Register error: the value specified as a register is incompati¬ 
ble with the code. 

S 

Syntax error: improperly formed expression. 

U 

Undefined label: label used does not exist. 

V 

Value error: improperly formed operand encountered in an 
expression. 

BAD DELIMITER 


STAT. Check command line for typing errors. 

Bad Load 

CCP error message, or SAVE error message. 

B d o s Err 

On d : 


Basic Disk Operating System error on the designated drive: CP/M 
replaces d: with the drive specification of the drive where the error 
occurred. This message is followed by one of the four phrases in the 
situations described below. 
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Table 1-1. (continued) 

Message Meaning 

Bdos Err On d: Bad Sector 

This message appears when CP/M finds no disk in the drive, when 
the disk is improperly formatted, when the drive latch is open, or 
when power to the drive is off. Check for one of these situations and 
try again. This could also indicate a hardware problem or a worn or 
improperly formatted disk. Press TC to terminate the program and 
return to CP/M, or press RETURN to ignore the error. 


Bdos Err On d s File R/0 

You tried to erase, rename, or set file attributes on a Read-Only file. 
The file should first be set to Read-Write (R/W) with the command: 
STAT filespec $R/W. 

Bdos Err On d: R/□ 

Drive has been assigned Read-Only status with a STAT command, or 
the disk in the drive has been changed without being initialized with 
a TC. CP/M terminates the current program as soon as you press any 
key. 


Bdos Err on d s Select 

CP/M received a command line specifying a nonexistent drive. CP/M 
terminates the current program as soon as you press any key. Press 
RETURN or CTRL-C to recover. 


Break "x" at c 

ED. “x” is one of the symbols described below and c is the command 
letter being executed when the error occurred. 

# Search failure. ED cannot find the string specified in an F, S, or 
N command. 

? Unrecognized command letter c. ED does not recognize the 
indicated command letter, or an E, H, Q, or O command is not 
alone on its command line. 
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Table 1-1. (continued) 

Message Meaning 

□ The file specified in an R command cannot be found. 

Buffer fuff. ED cannot put any more characters in the memory 
buffer, or the string specified in an F, N, or S command is too 
long. 

E Command aborted. A keystroke at the console aborted com¬ 
mand execution. 

F Disk or directory full. This error is followed by either the disk 
or directory full message. Refer to the recovery procedures 
listed under these messages. 

CANNOT CLOSE DESTINATION FILE---C f i 1 e s pe c > 

PIP. An output file cannot be closed. You should take appropriate 
action after checking to see if the correct disk is in the drive and that 
the disk is not write-protected. 

Cannot closer R/0 
CANNOT CLOSE FILES 

CP/M cannot write to the file. This usually occurs because the disk is 
write-protected. 

ASM. An output file cannot be closed. This is a fatal error that 
terminates ASM execution. Check to see that the disk is in the drive, 
and that the disk is not write-protected. 

DDT. The disk file written by a W command cannot be closed. This 
is a fatal error that terminates DDT execution. Check if the correct 
disk is in the drive and that the disk is not write-protected. 

SUBMIT. This error can occur during SUBMIT file processing. 
Check if the correct system disk is in the A drive and that the disk is 
not write-protected. The SUBMIT job can be restarted after reboot¬ 
ing CP/M. 
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Table 1-1. (continued) 

Message Meaning 

DESTINATION IS R/D t DELETE (Y/N>? 

PIP. The destination file specified in a PIP command already exists 
and it is Read-Only. If you type Y, the destination file is deleted 
before the file copy is done. 

Directory full 

ED. There is not enough directory space for the file being written to 
the destination disk. You can use the OXfilespec command to erase 
any unnecessary files on the disk without leaving the editor. 

SUBMIT. There is not enough directory space to write the $$$.SUB 
file used for processing SUBMITs. Erase some files or select a new 
disk and retry. 

Disk full 

ED. There is not enough disk space for the output file. This error can 
occur on the W, E, H, or X commands. If it occurs with X command, 
you can repeat the command prefixing the filename with a different 
drive. 

DISK READ ERRDR---Cf ilespec> 

PIP. The input disk file specified in a PIP command cannot be read 
properly. This is usually the result of an unexpected end-of-file. Cor¬ 
rect the problem in your file. 
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pus 


!" 

pip* 

peg 


pap 


jiap 


Table 1-1. (continued) 


Message 

Meaning 

DISK WRITE ERR0R---Cf i lespec> 

DDT. A disk write operation cannot be successfully performed dur¬ 
ing a W command, probably due to a full disk. You should either 
erase some unnecessary files or get another disk with more space. 

PIP. A disk write operation cannot be successfully performed during 
a PIP command, probably due to a full disk. You should either erase 
some unnecessary files or get another disk with more space and 
execute PIP again. 

SUBMIT. The SUBMIT program cannot write the $$$.SUB file to the 
disk. Erase some files, or select a new disk and try again. 

ERROR: 

BAD PARAMETER 

PIP. You entered an illegal parameter in a PIP command. Retype the 
entry correctly. 

ERROR: 

CANNOT OPEN SOURCE# LOAD ADDRESS hhhh 

LOAD. Displayed if LOAD cannot find the specified file or if no 
filename is specified. 

ERROR: 

CANNOT CLOSE FILE# LOAD ADDRESS hhhh 

LOAD. Caused by an error code returned by a BDOS function call. 
Disk might be write-protected. 

ERROR: 

CANNOT OPEN SOURCE# LOAD ADDRESS hhhh 

LOAD. Cannot find source file. Check disk directory. 

ERROR: 

DISK READ# LOAD ADDRESS hhhh 

LOAD. Caused by an error code returned by a BDOS function call. 
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Table 1-1. (continued) 


Message Meaning 

ERROR: DISK WRITE > LOAD ADDRESS hhhh 
LOAD. Destination disk is full. 

ERROR: INVERTED LOAD ADDRESS > LOAD ADDRESS hhhh 

LOAD. The address of a record was too far from the address of the 
previously-processed record. This is an internal limitation of LOAD, 
but it can be circumvented. Use DDT to read the HEX file into 
memory, then use a SAVE command to store the memory image file 
on disk. 

ERROR: NO MORE DIRECTORY SPACE > LOAD ADDRESS hhhh 

LOAD. Disk directory is full. 

Error on line nnn message 

SUBMIT. The SUBMIT program displays its messages in the format 
shown above, where nnn represents the line number of the SUBMIT 
file. Refer to the message following the line number. 

FILE ERROR 

ED. Disk or directory is full, and ED cannot write anything more on 
the disk. This is a fatal error, so make sure there is enough space on 
the disk to hold a second copy of the file before invoking ED. 

FILE EXISTS 

You have asked CP/M to create or rename a file using a file specifica¬ 
tion that is already assigned to another file. Either delete the existing 
file or use another file specification. 

REN. The new name specified is the name of a file that already exists. 
You cannot rename a file with the name of an existing file. If you 
want to replace an existing file with a newer version of the same file, 
either rename or erase the existing file, or use the PIP utility. 
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Table 1-1. (continued) 


Message Meaning 
File exists > erase it 

ED. The destination filename already exists when you are placing the 
destination file on a different disk than the source. It should be erased 
or another disk selected to receive the output file. 

** FILE IS READ/ONLY ** 

ED. The file specified in the command to invoke ED has the Read- 
Only attribute. Ed can read the file so that the user can examine it, 
but ED cannot change a Read-Only file. 


File Not Found 

CP/M cannot find the specified file. Check that you have entered the 
correct drive specification or that you have the correct disk in the 
drive. 

ED. ED cannot find the specified file. Check that you have entered 
the correct drive specification or that you have the correct disk in the 
drive. 

STAT. STAT cannot find the specified file. The message might appear 
if you omit the drive specification. Check to see if the correct disk is 
in the drive. 


FILE NOT FOUND--{f i lespec} 

PIP. An input file that you have specified does not exist. 


Filename required 

ED. You typed the ED command without a filename. Reenter the ED 
command followed by the name of the file you want to edit or create. 


hhhh??=dd 


DDT. The ?? indicates DDT does not know how to represent the 
hexadecimal value dd encountered at address hhhh in 8080 assembly 
language, dd is not an 8080 machine instruction opcode. 
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Table 1-1. (continued) 

Message Meaning 
Insufficient m e m o r y 

DDT. There i? not enough memory to load the file specified in an R 
or E command. 


Invalid A s si$nm e nt 

STAT. You specified an invalid drive or file assignment, or misspelled 
a device name. This error message might be followed by a list of the 
valid file assignments that can follow a filename. If an invalid drive 
assignment was attempted the message Use: d: = RO is displayed, 
showing the proper syntax for drive assignments. 

Invalid control character 

SUBMIT. The only valid control characters in the SUBMIT files of 
the type SUB are " A through * Z. Note that in a SUBMIT file the 
control character is represented by typing the circumflex, ", not by 
pressing the control key. 

INVALID DIGIT--*Cfilespec> 

PIP. An invalid HEX digit has been encountered while reading a 
HEX file. The HEX file with the invalid HEX digit should be cor¬ 
rected, probably by recreating the HEX file. 

Invalid Disk Assignm e n t 

STAT. Might appear if you follow the drive specification with any¬ 
thing except = R/0. 

INVALID DISK SELECT 

CP/M received a command line specifying a nonexistent drive, or the 
disk in the drive is improperly formatted. CP/M terminates the cur¬ 
rent program as soon as you press any key. 


mm 
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Table 1-1. (continued) 

Message Meaning 

INVALID DRIVE NAME (Use A ♦ B » C > or D) 

SYSGEN. SYSGEN recognizes only drives A, B, C, and D as valid 
destinations for system generation. 

Invalid File Indicator 

STAT. Appears if you do not specify RO, RW, DIR, or SYS. 

INVALID FORMAT 

PIP. The format of your PIP command is illegal. See the description 
of the PIP command. 

INVALID HEX DIGIT 
LOAD ADDRESS hhhh 
ERROR ADDRESS hhhh 
BYTES READ: 
hhhh 

LOAD. File contains incorrect HEX digit. 

INVALID MEMORY SIZE 

MOVCPM. Specify a value less than 64K or your computer’s actual 
memory size. 

INVALID SEPARATOR 

PIP. You have placed an invalid character for a separator between 
two input filenames. 

INVALID USER NUMBER 

PIP. You have specified a user number greater than 15. User numbers 
are in the range 0 to 15. 
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Table 1-1. (continued) 

Message Meaning 


USER. You specified a number greater than fifteen for a user area 
number. For example, if you type USER 18<cr>, the screen displays 
18?. 


NO DIRECTORY SPACE 

ASM. The disk directory is full. Erase some files to make room for 
PRN and HEX files. The directory can usually hold only 64 
filenames. 


NO DIRECTORY S PACE - - -C f i 1 e s p e c > 

PIP. There is not enough directory space for the output file. You 
should either erase some unnecessary files or get another disk with 
more directory space and execute PIP again. 

NO FILE---Cfilespec> 

DIR, ERA, REN, PIP. CP/M cannot find the specified file, or no files 
exist. 

ASM. The indicated source or include file cannot be found on the 
indicated drive. 

DDT. The file specified in an R or E command cannot be found on 
the disk. 


NO INPUT FILE PRESENT ON DISK 

DUMP. The file you requested does not exist. 

No wemo ry 

There is not enough (buffer?) memory available for loading the pro¬ 
gram specified. 
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Table 1-1. (continued) 

Message Meaning 
NO SOURCE FILE ON DISK 

S YSGEN. S YSGEN cannot find CP/M either in CP/Mxx ♦COM form 
or on the system tracks of the source disk. 

NO SOURCE FILE PRESENT 

ASM. The assembler cannot find the file you specified. Either you 
mistyped the file specification in your command line, or the filetype is 
not ASM. 


NO SPACE 

SAVE. Too many files are already on the disk, or no room is left on 
the disk to save the information. 


No SUB file present 

SUBMIT. For SUBMIT to operate properly, you must create a file 
with filetype of SUB. The SUB file contains usual CP/M commands. 
Use one command per line. 

NOT A CHARACTER SOURCE 

PIP. The source specified in your i y IP command is illegal. You have 
probably specified an output device as a source. 

** NOT DELETED ** 

PIP. PIP did not delete the file, which might have had the R/O attri¬ 
bute. 

NOT FOUND 

PIP. PIP cannot find the specified file. 
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Table 1-1. (continued) 

Message Meaning 
OUTPUT FILE WRITE ERROR 

ASM. You specified a write-protected disk as the destination for the 
PRN and HEX files, or the disk has no space left. Correct the prob¬ 
lem before assembling your program. 

Parameter error 

SUBMIT. Within the SUBMIT file of type sub, valid parameters are 
$0 through $9. 

PARAMETER ERROR t TYPE RETURN TO IGNORE 

SYSGEN. If you press RETURN, SYSGEN proceeds without proces¬ 
sing the invalid parameter. 

QUIT NOT FOUND 

PIP. The string argument to a Q parameter was not found in your 
input file. 

Read error 

TYPE. An error occurred when reading the file specified in the type 
command. Check the disk and try again. The STAT filespec com¬ 
mand can diagnose trouble. 

READER STOPPING 

PIP. Reader operation interrupted. 

Record Too Lon 3 

PIP. PIP cannot process a record longer than 128 bytes. 

Requires CP/M 2*0 or later 

XSUB. XSUB requires the facilities of CP/M 2.0 or newer version. 
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Table 1-1. (continued) 

Message Meaning 

Requires CP/M 2*0 or new for operation 

PIP. This version of PIP requires the facilities of CP/M 2.0 or newer 
version. 


START NOT FOUND 

PIP. The string argument to an S parameter cannot be found in the 
source file. 


SOURCE FILE INCOMPLETE 

SYSGEN. SYSGEN cannot use your CP/M source file. 

SOURCE FILE NAME ERROR 

ASM. When you assemble a file, you cannot use the wildcard charac¬ 
ters * and ? in the filename. Only one file can be assembled at a time. 

SOURCE FILE READ ERROR 

ASM. The assembler cannot understand the information in the file 
containing the assembly-language program. Portions of another file 
might have been written over your assembly-language file, or in¬ 
formation was not properly saved on the disk. Use the TYPE com¬ 
mand to locate the error. Assembly-language files contain the letters, 
symbols, and numbers that appear on your keyboard. If your screen 
displays unrecognizable output or behaves strangely, you have found 
where computer instructions have crept into your file. 

SYNCHRONIZATION ERROR 

MOVCPM. The MOVCPM utility is being used with the wrong 
CP/M system. 

"SYSTEM" FILE NOT ACCESSIBLE 

You tried to access a file set to SYS with the STAT command. 


puns 
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Table I-l. (continued) 

Message Meaning 
** TOO MANY FILES ** 

STAT. There is not enough memory for STAT to sort the files spe¬ 
cified, or more than 512 files were specified. 

UNEXPECTED END OF HEX FILE---C f i 1 e s pe c > 

PIP. An end-of-file was encountered prior to a termination HEX 
record. The HEX file without a termination record should be cor¬ 
rected, probably by recreating the HEX file. 

Unrecognised Destination 

PIP. Check command line for valid destination. 

Use: STAT d:=R0 

STAT. An invalid STAT drive command was given. The only valid 
drive assignment in STAT is STAT d: = RO. 

VERIFY ERROR:---Cfi lespec) 

PIP. When copying with the V option, PIP found a difference when 
rereading the data just written and comparing it to the data in its 
memory buffer. Usually this indicates a failure of either the destina¬ 
tion disk or drive. 


WRONG CP/M VERSION (REQUIRES 2*0) 

XSUB ACTIVE 

SUBMIT. XSUB has been invoked. 

XSUB ALREADY PRESENT 

SUBMIT. XSUB is already active in memory. 



i 
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Table 1-1. (continued) 

Message 

Meaning 

Y our i nput? 


If CP/M cannot find the command you specified, it returns the com¬ 
mand name you entered followed by a question mark. Check that 
you have typed the command line correctly, or that the command 
you requested exists as a .COM file on the default or specified disk. 


End of Appendix I 
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Appendix J 

CP/M on the BBC Microcomputer 
Technical Notes 


Screen Control 

There are three techniques that a CP/M application program can use to 
control the BBC Microcomputer's screen: 

BBC Microcomputer Control Codes 
Terminal Emulator Control Codes 
GSX Functions 


BBC Microcomputer Control Codes 

All of the functions of the BBC Microcomputer normally accessed via 
the VDU command can be accessed through CP/M by sending an appropriate 
control code. These are explained in chapter 34 of the BBC 
Microcomputer User Guide and are summarised on page 378. For example, 
sending the sequence (as hexadecimal bytes) IF 10 04 would position 
the cursor to cell x=16, y=4. 


Terminal Emulator Control Codes 

To allow existing CP/M applications to use basic terminal functions in 
a simple way, a terminal interface has been defined. This is by 
default disabled, but can be enabled, disabled or tested by assembler 
programs as follows: 

To enable terminal mode 

LD A, 1 
CALL 0FFC8H 

To disable terminal mode 

LD A, 0 
CALL 0FFC8H 

To test terminal mode 

LD A,OFFH 
CALL FFC8H 

In all cases, the state of the terminal mode before the call is 
returned in A: 

A = 0 terminal mode was disabled 

A = 1 terminal mode was enabled 
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An extra program is provided on the utilities disc: TERM.COM. This 
turns terminal mode on or off from the CCP. 

TERM ON to enable terminal mode 
TERM OFF to disable terminal mode 

When the terminal mode is enabled, the following control codes and 
escape sequences can be used to control the screen. All numbers are 
hexadecimal. 


07 


Bleep 

08 


Move left one character 

09 


Move right one character 

0A 


Move down one line 

0B 


Move up one line 

OC 


Clear screen 

0D 


Carriage return 

IB 

3D YY XX 

Position cursor to (XX-20, YY-20) 

IB 

3E ?...? 00 

Send sequence of bytes X...X to 
where each byte X sent = ?-20 

IB 

3F 

Clear to end of screen 

IB 

40 

Clear to end of line 

IE 


Home cursor 


Notes: 


To send escape (IB) to the screen with the terminal emulator enabled, 
the sequence IB 3E 3B 00 should be sent. 

The clear to end of line and clear to end of screen functions are 
intended for 80 column screens of full dimensions, and will work in 
screen modes 0 and 3 only. They will reset the text window to the 
full screen. 


GSX Functions 


These are described in the GSX Addendum. 
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Operating system calls 

The operating system calls of the BBC Microcomputer can be accessed 
directly from the Z80 in a similar manner to the BBC Microcomputer 
itself. Operating system calls can be made via a jump table starting 
at address FFCEH. The entry point for each routine corresponds with 
the equivalent address on the 6502, eg the WRCH routine is entered at 
FFEEH. All operating system calls (apart from OSARGS - see below) 
take parameters in Z80 registers A, H and L corresponding to A, Y and 
X on the 6502. For all calls that use the carry flag on the 6502 this 
still applies on the Z80. 

For example: 


LD A,41H ;Character to be written in A 

CALL OFFEEH ?Call OSWRCH to write character 

and 


LD A, 5 

LD L, 2 

CALL 0FFF4H 


*FX 5,2 => A set to 5 
L set to 2 

Call OSBYTE routine equivalent to *FX 5,2 


Interception of any operating system call can be achieved by simply 
changing the address field of the relevant jump to point to the 
required user routine. 


The new memory map is shown below 


Address (Hex) 

Purpose 

FFFE 

INT vector - reserved, for the Z80 
operating system 

FFFC 

Event vector 

FFFA 

BRK vector 

FFF7 

OSCLI - H,L point to command line 

FFF4 

OSBYTE - A = OSBYTE number 

H,L are parameters 

FFF1 

OSWORD - A = OSWORD number 

H,L point to control block 

FFEE 

OSWRCH - A = character 

FFE7 

OSNEWL - Write linefeed, carriage 
return to screen 

FFE3 

OSASCI - Write character in A to screen 
plus linefeed if A = ODH 

FFEO 

OSRDCH - A = character 
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(SUSSI 


FFDD 

OSFILE - A = Operation type 

H,L point to control block 


FFDA 

OSARGS - A = Operation type , E = Handle 
H,L point to control block 

PSP'] 

FFD7 

OSBGET - A = Byte 

H = File handle 

RSSFj 

FFD4 

OSBPUT - A = Byte 

H = File handle 


FFD1 

OSBGBP - A = Operation type 

HL point to control block 


FFCE 

OSFIND - A = Operation type 

H,L point to filename (A*0) 



H = file handle (A=0) 


FFC8 

TERM - A = 0 Switch off terminal mode 

(default) 

A = 1 Switch on terminal mode 



A = FF Test terminal mode 


FF82 

Fault pointer 


FF80 

Escape flag - top bit set if escape 
condition exists 
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Faults and events 


6502 Faults 

When a fault is generated by the 6502 host processor the Z80 is 
interrupted and the fault number and string are passed across the Tube 
and placed in an fault buffer. The pointer at FF82H is then set to 
point to the fault number and the Z80 operating system indirects 
through the BRK vector at FFFAH. 


Z80 Faults 

Faults can also be generated on the Z80 using the RST 38H instruction. 
All Z80 generated faults should adhere to the following convention: 

RST 38H Value FFH 

Fault number 
Fault string 

Terminator Value 00H 


Events 

When an event is detected by the 6502 operating system the event 
parameters A , Y and X are passed across the Tube to Z80 registers A , 
H and L respectively. The Z80 operating system then indirects through 
the event vector at FFFCH which is initialised to point to a Z80 RET 
instrution. 


Escape processing 

When the escape code is detected from the keyboard the top bit of the 
escape flag at FF80H is set. An escape condition should be detected by 
testing this bit and acknowledged by OSBYTE call 7EH. The escape flag 
should be reset or set using OSBYTE calls 7CH or 7DH. 


Interrupt handling 

NMI Non-maskable interrupt 

This interrupt is reserved for use by the Z80 operating system and 
cannot be intercepted by the user. 

INT Interrupt request 

When an INT is detected the Z80 operating system indirects through 
location FFFEH. All unrecognised interrupts are passed to a user INT 
routine at FFBOH in the jump table. The address field at FFB1H should 
be changed to point to the required user INT routine. This routine 
must preserve all registers and return using instructions: 

El ; enable interrupts 

RETI ; return from maskable interrupt routine 
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Character I/O under CP/M 


Device assignments 

The object of this implementation is to allow the user to 
redirect I/O either with the IOBYTE as on a normal CP/M system, or 
with OSBYTE calls as on a normal BBC machine. 

The following logical devices are present on a CP/M system: 

CON: the user console 
LST: the printer 
RDR: the paper tape reader 
PUN: the paper tape punch 

These logical devices can be assigned to the following physical 
devices: 

UC1: the user defined console device 
CRT: the screen and keyboard 
TTY: the RS423 serial lines 
LPT: the printer 

BAT: batch mode (input from RDR: and output to LST:) 

PTR: paper tape reader - reassigned as the keyboard 
PTP: paper tape punch - reassigned as the screen 

CP/M also has the following physical devices which are all 
defined as null devices in this implementation: 

UR1: 

UR2: 

UP1: 

UP2: 

UL1: 

Null devices throw away any output and return end of file (1AH) on 
input. 

The default setting of IOBYTE has the following assignments: 


CON: 

is 

UC1: 

LST: 

is 

LPT: 

RDR: 

is 

TTY: 

PUN: 

is 

TTY: 


Device characteristics 

The physical devices have the following characteristics: 

UC1: the user defined console device. 

This is the default console device. It is also the fastest of the 
console devices since it uses the standard BBC input and output 
streams. These streams can be altered by using OSBYTE calls in the 
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normal BBC manner, so if you don't want to use the IOBYTE facility 
you can treat the machine's I/O as that of a normal BBC machine, 
using the STAR command. 

CRT: the screen and keyboard. 

Here input is taken from the keyboard and output is sent to the 
screen. When using this device it's characteristics cannot be 
changed with OSBYTE calls. 

TTY: the RS423 serial lines. 

The RS423 serial lines can be accessed using this device. The 
default baud rate setting for the TTY: is 9600 baud (this can be 
changed by the appropriate OSBYTE call). No events are generated by 
ESCAPE characters, and non-ASCII.codes cannot be programmed on the 
function keys. The normal BBC handshaking using CTS RTS is 
implemented. You should not enable the cassette drivers or disable 
the RS 423 input while using this device. Although a serial printer 
can be driven by this device you should be aware that this bypasses 
the normal printer functions, such as setting an ignore 
character or being informed that the printer has stopped. It is 
therefore better to use the LPT: device and set it to a serial 
printer with the appropriate OSBYTE call. 

LPT: the printer. 

This is the standard BBC printer driver. It can be changed to suit 
the particular printer in use. The default setting is the parallel 
printer, ignoring linefeeds. It is recommended that when connecting a 
serial printer the IOBYTE be left unchanged and the LPT: device 
altered with the appropriate OSBYTE call. The alternative is 
to use the IOBYTE to select the TTY: driver but this does not carry 
out any of the standard printer functions. 

BAT: batch mode (input from RDR: and output to LST:). 

This device takes its input from the logical device RDR:. This can 
in turn be assigned to any of the relevant physical devices. The 
output goes to the logical device LST:, which can in turn be 
reassigned to the relevant physical device. 

PTR: paper tape reader - reassigned as the keyboard. 

In the absence of a paper tape reader this device is the 

keyboard. 

PTP: paper tape punch - reassigned as the screen. 

In the absence of a paper tape punch this device is the screen. 
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Boot options on the BBC CP/M system 

The BBC CP/M system is provided with an option to allow automatic 
execution of programs on initial startup. The system checks disc A, 
user area 0, for the presence of certain files and will take 
appropriate action if these are found. On subsequent warm starts no 
action is taken. 

There are two possible types of BOOT file; BOOT.COM and BOOT.SUB. 
B00T.C0M takes precedence. If it is present then it is run as a 
normal .COM program. If there is no BOOT.COM but there is a 
BOOT.SUB then this will be submitted. If both BOOT.COM and 
BOOT.SUB are present then the BOOT.COM is run and the BOOT.SUB is 
ignored. 

BOOT.COM is a normal CP/M COM file, ie. a machine code program that 
is loaded and run directly. If this is present then it is loaded and 
run before the initial prompt. An example of this would be to 
rename STAT.COM to BOOT.COM and so be informed of the free space on 
the disc when starting up. Another use would be to start running an 
applications program immediately so that the users never need deal 
directly with the CP/M operating system. 

BOOT.SUB is a normal CP/M SUBMIT file, ie. it is a text file 
containing a list of CP/M commands to be executed. If BOOT.COM 
isn't present then CP/M looks for BOOT.SUB. If it is found then CP/M 
attempts to submit it. To submit it the file SUBMIT.COM must be 
present on disc A, user 0. If it is missing then a message to that 
effect will be given and the BOOT option ignored. 
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1-2, 4-1,5-1, 6-1 
Console Input function, 5-12 
Console Output function, 5-12 
CONST, 6-21 
Constant, 3-5 
Control characters, 2-19 
Control functions, 1-13 
CTRL-Z character, 5-7 
Copy files, 1-25 
CPU state, 4-3, 4-4 
cr (carriage return), 2-10 
Create files, 1-35 
Create system disk, 1-37 
Creating COM files, 1-24 
Currently logged disk, 1-3, 1-7, 1-15, 1-36 
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D 

Data allocation size, 6-31 
Data block number, 6-32 
DB statement, 3-15 
DDT commands, 4-4, 6-9 
DDT nucleus, 4-11 
DDT prompt, 4-2 
DDT sign-on message, 4-1 
Decimal constant, 3-5 
Default FCB, 4-7 
Delete File function, 5-22 
DESPOOL, 6-17 
Device assignment, 1-16 
DIR, 1-9 

DIR attribute, 1-20 
dir parameter, 6-35 
Direct console I/O function, 5-14 
Direct Memory Address, 5-27 
Directory, 1-9 

Directory code, 5-19, 5-20, 5-21, 5-22, 
5-23,5-24,5-25 
Disassembler, 4-4,11 
Disk attributes, 1-15 
Disk drive name, 1-6, 7 
Disk I/O functions, 5-17—5-35 
Disk parameter block, 6-30 
Disk parameter header, 6-28 
Disk parameter table, 6-28 
Disk statistics, 1-15 
Disk-to-disk copy, 1-27 
DISKDEF macro, 6-34 
Diskette format, 1-47 
DISKS macro, 6-34 
Display file contents, 1-11 
dks parameter, 6-35 
DMA, 5-27 
DMA address, 5-8 
dn parameter, 6-35 
DPBASE, 6-29 


Drive characteristics, 1-21 
Drive select code, 5-9 
Drive specification, 1-7 
DS statement, 3-16 
DUMP, 1-41 5-40 
DW statement, 3-15 


E 

ED, 1-35, 2-1—2-22, 6-6 
ED commands, 2-8,19 
ED errors, 2-18 
Edit command line, 1-12 
8080 CPU registers, 4-10 
8080 registers, 3-6 
end-of-file, 1-28, 5-7 
END statement, 3-4, 3-11 
EMDEF macro, 6-35 
ENDIF statement, 3-13 
EQU statement, 3-12 
ERA, 1-8 
Erase files, 1-8 

Error messages, 1-44, 2-18, 3-24 
Expression, 3-4 
Extents, 1-19 


F 

FBASE, 5-2 

FCB, 5-8,5-9 

FCB format, 5-8, 5-9 

FDOS (operations), 5-1, 5-4 

File attributes, 1-20 

File compatibility, 1-35 

File control block (FCB), 5-8, 5-9 

File expansion, 6-2 

File extent, 5-8 

File indicators, 1-20 

File names, 1-4 
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File reference, 1-4 
File statistics, 1-15, 1-19 
Filetype, 5-6 
Find command, 2-11 
fsc parameter, 6-35 

G 

Get ADDR (Alloc) function, 5-27 
Get ADDR (Disk Parms) function, 5- 
29 

Get Console Status, 5-17 
Get I/O Byte function, 5-15 
Get Read/Only Vector function, 5-28 
GETSYS, 6-3, 6-11 


H 

Hexadecimal constant, 3-5 
HOME subroutine, 6-20, 22 


I 

Identifier, 3-3, 3-5 
IF statement, 3-13 
Initialized storage areas, 3-15 
In-line assembly language, 4-4 
Insert mode, 2-7 
Insert String, 2-12 
IOBYTE function, 6-17—6-19 

J 

Jump vector, 6-15 
Juxtaposition command, 2-15 


K 

Key fields, 5-34 

L 

Label field, 3-3 
Labels, 3-3, 3-4, 3-16 
Library read command, 2-16 
Line-editing control characters, 2-9, 4- 
2,5-16 

Line-editing functions, 1-12 

Line numbers, 2-5 

LIST, 6-17, 6-21 

List Output function, 5-14 

LISTST, 6-24 

LOAD, 1-24 

Logged in, 1-3 

Logical devices, 1-16, 1-28, 6-17 
Logical extents, 5-8 

Logical-physical assignments, 1-18, 6- 
19 

Logical to physical device mapping, 6- 
18 

Logical to physical sector translation, 
6-24, 6-35 
Isc parameter, 6-35 

M 

Macro command, 2-17 
Make File function, 5-25 
Memory buffer, 2-1—2-7 
Memory image, 4-3, 6-6, 6-7 
Memory size, 1-42, 6-3, 6-8 
MOVCPM, 1-42, 6-7 
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R 


Negative bias, 6-7 

Radix indicators, 3-5 


o 

Random access, 5-31, 5-32, 5-46 

Random record number, 5-32 

READ, 6-23 


[o] parameter, 6-35 

Read Console Buffer function, 5-16 

Read only, 1-20 


Octal constant, 3-5 

Read/only status, 1-20 


ofs parameter, 6-35 

Read random error codes, 5-31 

On-line status, 5-19 

Read Random function, 5-30 


Open File function, 5-19 

READ routine, 6-20 


Operand field, 3-4, 3-6 

Read Sequential function, 5-23 

Operation field, 3-4, 3-16 

Read/write, 1-20 


Operators, 3-9, 3-16 

READER, 6-18,21 


ORG directive, 3-11 

Reader Input function, 5-13 


P 

REN, 1-10 

Rename file function, 5-25 

Reset Disk function, 5-18 


Page zero, 6-26 

Reset Drive function, 5-35 

Reset state, 5-18 


Patching the CP/M system, 6-3 

Return Current Disk function, 5-26 


Peripheral devices, 6-17 

Return Log-in Vector function, 5-26 

Physical devices, 1-17, 6-17 

Return Version Number function, 5-18 


Physical file size, 5-33 

R/O, 1-20 


Physical to logical device assignment, 

R/O attribute, 5-29 


1-18, 6-19 

R/O bit, 5-28 


PIP devices, 1-28 

R/W, 1-20 


PIP parameters, 1-31 



Print String function, 5-15 

PRN file, 3-1 

S 


Program counter,4-4,4-6, 4-7, 4-11 



Program tracing, 4-9 

SAVE, 1-11 


Prompt, 1-3 

SAVE command, 4-3 


Pseudo-operation, 3-10 

Search for First function, 5-21 


PUNCH, 6-17, 6-21 

Search for Next function, 5-22 


Punch Output function, 5-13 

Search strings, 2-11 


PUTSYS, 6-4, 6-11 

Sector allocation, 6-13 
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SECTRAN, 6-24 

SELDSK, 6-19, 6-22, 6-30 

Select Disk function, 5-19 

Sequential access, 5-8 

Set DMA address function, 5-27 

Set File Attributes function, 5-29 

Set/Get User Code function, 5-30 

Set I/O Byte function, 5-15 

Set Random Record function, 5-34 

SET statement, 3-13 

SETDMA, 6-23 

SETSEC, 6-23 

SETTRK, 6-22 

Simple character I/O, 6-17 

Size in records, 1-19 

skf parameter, 6-35, 6-37 

Source files, 5-7 

Stack pointer, 5-6 

STAT, 1-15,6-17,6-38 

Stop console output, 1-13 

String substitutions, 2-14 

SUBMIT, 1-39 

SYS attribute, 1-20 

SYSGEN, 1-37, 6-10 

System attribute, 2-19, 5-29 

System parameters, 6-20 

System (re)initialization, 6-16 

System Reset function, 5-11 

T 

Testing and debugging of programs, 4- 
1 

Text transfer commands, 2-3 
TPA (Transient Program Area), 1-2, 5- 
1 

Trace mode, 4-10 
Transient commands, 1-3, 1-14 
Transient Program Area (TPA), 1-2, 5- 
1 


Translate table, 6-37 
Translation vectors, 6-30 
TYPE, 1-11 

u 

ufn, 1-4, 1-7 

Unambiguous file reference, 1-4, 1-7 
Uninitialized memory, 3-16 
Untrace mode, 4-10 
USER, 1-12 

USER numbers, 1-12, 1-22, 5-30 

V 

Verify line numbers command, 2-6, 21 
Version independent programming, 5- 
18 

Virtual file size, 5-33 

W 

Warm start, 5-2, 6-20 
WBOOT entry point, 6-20 
WRITE, 6-24 

Write Protect Disk function, 5-28 
Write random error codes, 5-32 
Write Random function, 5-32 
Write Random with Zero Fill function, 
5-35 

Write routine, 6-24 

Write Sequential function, 5-24 

X 

XSUB, 1-41 
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Introduction 


GSX-80 adds graphics capability to the CP/M system running on your BBC 
Microcomputer. GSX stands for Graphics System Extension, and is just 
that. It works in the same way as the CP/M operating system and allows 
graphics programs to be transferred unchanged from machine to machine. 

This guide is designed to provide an overview of the features of 
GSX-80 on the BBC Microcomputer, and how these features might be used. 
GSX has been provided to allow access to commercially written graphics 
applications. You should use this guide in conjunction with support 
documentation for the applications you wish to use. 

Various programming languages available to run under CP/M have a 
built-in interface to GSX-80. Programs written in these languages will 
transfer directly to the BBC Microcomputer with Z80 second processor. 
Further details will be found in the appropriate language reference 
manual. There are chapters later in this guide on using GSX from other 
languages. Technical details of GSX-80 will be found in the Digital 
Research Manual, GSX-80 Programmers Guide. 




1 What is GSX? 


The user's view 


Not all the graphics input and output devices which can be used with 
the BBC Microcomputer have the same facilities or capabilities. A 
simple task to the BBC Microcomputer such as drawing a solid red 
triangle on a blue background is difficult to accomplish on a colour 
plotter and impossible on a 'standard' matrix printer! If GSX is used 
by your application programs, then it will handle the differences and 
simulate (within reason) the features the device cannot provide. Even 
with GSX there are limits to this simulation capability, so you should 
choose the features required with the devices in mind. 




GSX consists of a set of programs, one per device, to translate your 
device-independent operators into device-specific commands. These are 
called 'device drivers'. For example, although every device has a 
co-ordinates system of some kind, direct access to co-ordinates in the 
range X=0 1279 and Y=0 to 1023 on the BBC Microcomputer and vertical 
and horizontal increments on a printer, there is very little 
standardisation. The device drivers ensure that your problem oriented 
co-ordinates system is translated into the appropriate co-ordinates 
for the device being used, so ensuring correctly positioned text of 
the right size and correct orientation. 

In this way, you leave it up to GSX to fetch the correct device driver 
from disc and load it into the memory of the Z80, ready to obey the 
application program's graphics commands. In return, however, you have 
to add a few special instructions to your programs or CP/M command 
sequences to inform GSX which device you are actually using. 

GSX does not assume that a graphics device is simply an output device 
(such as a plotter), but if required any device can also be used for 
input. GSX categorises input devices as follows: 


Locator 

Valuator 

Choice 

Input String 


2-D position eg Mouse, Light Pen, Joystick 
Analog 1-D value (eg A to D converter) 

Selection from a set of values (eg Cursor keys) 
Keyboard input 


Hie programmer's view 


GSX consists of the device-independent Graphics Device Operating 
System (GDOS) and the device-dependent Graphics Input/Output System 
(GIOS). The graphics application makes calls on the GDOS. The GDOS 
both loads the appropriate device driver into the GIOS area and makes 
low level function calls on the GIOS. 

A graphics application program runs in the Transient Program Area 
(TPA), just like any other user program, but first reserves space for 
the GIOS and loads the GDOS at the top of the TPA. Rather than include 
the GIOS device drivers and the GDOS in each application program, 
these are loaded from disc as needed. The GENGRAF utility is used to 
incorporate the GSX loader in the application program. The loader runs 
at the start of the application and loads in the GDOS from the from 
the file GSX.SYS and the list of device drivers from ASSIGN.SYS. The 
GDOS dynamically loads device drivers from disc. 


3 






2 How to use GSX 
Setting up GSX 


On the CP/M Utilities disc are some special files for GSX to use. They 
are: 


ASSIGN.SYS 

GSX.SYS 

DDBBCO.PRL 

DDBBC1.PRL 

DDFXLR8 

DDFXHR8 

DDOKI84 

GENGRAF.COM 

ASSIGN.SYS contains the Assignment Table. This 'assigns' logical 
device numbers to the device drivers. Application programs are written 
using logical devices, and so simply changing the assignment table is 
all that is needed to specify which real devices will be used. 


GSX.SYS contains GSX itself (the GDOS). 


DD-RL are the device drivers provided with the system. You should 

consult Acorn Computers Limited Customer Service Department if you 
wish to use other devices, and the Digital Research technical manuals 
if you wish to write your own. 

GENGRAF.COM is a program which adds the GSX loader to a graphics 
application program. This will only be used if you are writing or 
modifying your own graphics applications programs. 


pm 


ASSIGN.SYS contains one line per device driver assignment. Each line 
consists of a two-digit logical device number followed by a space and 
the filename of the appropriate device driver, for example 


01 BrDDBBCl 


assigns logical device number 01 to be the BBC Microcomputer display 
in Mode 1 -for which the device driver is DDBBC1.PRL from drive B. 


For compatibility with other GSX systems, it is recommended that 
use logical device numbers from 01 to 10 for terminals, 11-20 
plotters and 21-30 for printers. 0 is used for the default console. 


you 

for 


It is important that the largest device driver is the first in the 
list in ASSIGN.SYS. Use STAT to find which this is. 

To create an application disc which uses GSX: 


— 1. Copy the required device drivers onto the application disc using 

f**" the PIP utility. 


2. Copy GSX.SYS 


3. If necessary edit ASSIGN.SYS to match the logical numbers used in 
the application and the device drivers available, and copy this across 
too. 


This disc can then be used as a GSX disc by being in one disc drive 


5 



when another disc containing GSX application programs is used; 
alternatively the application programs can be put onto this disc. ***! 

Invoking GSX 

You should ensure that the logged in drive contains: 

ASSIGN.SYS (which references the logged in drive) 

The device drivers listed in ASSIGN.SYS 
GSX.SYS • 

The application programs you wish to run can be on any disc, and are 
run simply by typing in their filenames, just like running a normal 
application program. 



3 Writing application programs to use GSX 

This chapter summarises the technical details of using the 
device-independent graphics from an application program. It will 
provide an overview of how to interface to the Graphics Device 
Operating System (GDOS). Full details of the the function calls and 
their parameters will be found in the Digital Research manual GSX-80 
Programmers Guide. 

The GDOS 


The application program invokes the graphics features via calls to the 
GDOS. The GDOS handles the conversion of normalised co-ordinates (the 
device-independent co-ordinate system used by GSX) to device-dependent 
co-ordinates. It also loads any device drivers needed to control the 
actual graphics devices in use. 


The application program is written just like any other CP/M 
application program, but contains extra calls to the BDOS to invoke 
the GDOS functions. The BDOS will only recognise GDOS functions if GSX 
has been loaded, and so an extra stage in the program development is 
required. After the program has been assembled or compiled and linked 
to produce a .COM file, the program GENGRAF is run to add the GSX 
loader to the application program. Then the application is ready to be 
run as described in section 2 of this guide. 

For example: A program called DRAWIT 


Write graphics application in Pascal/MT+ say 
Compile and Link with Runtime system giving 
Type GENGRAF DRAWIT to add GSX loader giving new 


DRAWIT.SRC 
DRAWIT.COM 
DRAWIT.COM 


The GDOS is invoked by a BDOS function call with code 115. For code 
115 to be recognised, it is necessary to have started GSX from the GSX 
loader. The application should use Normalised Device Coordinates when 
using GDOS functions. These are in the range 0 to 32767 in both the X 
and Y axes. GDOS converts these co-ordinates to those of the device 
using data passed from the device driver when the graphics device was 
opened. The full scale co-ordinates are always mapped onto the full 
dimensions of the device in each axis, thus ensuring that all the 
graphics display is visible on the device 



GDOS calls 


Invoked by BDOS call with function 115 (73H) and passing a parameter 
block. 


LD C, 73H 
LD DE, PARAMB 
CALL 0005H 


function code 
parameter block 
BDOS call 


The details of the call %re provided in the parameter block, which 
contains data as follows: 


Input 


Bytes 

0,1 

2,3 

4,5 

6,7 

8,9 


Control array 

CONTROL (1) 
CONTROL (2-3) 
CONTROL (4-5) 
CONTROL (6-... 


Address of: 

control array (CONTRL) 

input parameter array (INTIN) 

input point co-ordinate array (PTSIN) 

output parameter array (INTOUT) 

output point co-ordinate array (PTSOUT) 


opcode for driver function 
number of vertices in input point array 
length of input parameter array 
dependent on the function 






Parameter array 

INTIN (1-...) array of input parameters 
Co-ordinate array 

PTSIN (1-...) array of input co-ordinates. Each point is given 
by an X and a Y co-ordinate (2 bytes each). 
The number of points depends on the function. 

Output 

Control array 

CONTROL (3-4) 

CONTROL (5) 

CONTROL (6-...) dependent on the function 
Parameter array 

INTOUT (1-...) array of output parameters 
Point co-ordinate array 

PTSOUT (1-...) array of output co-ordinates - as for input 

Note any lengths and number of parameters of unused arrays must be 
zero. 


number of vertices in output point array 
length of output co-ordinate array 
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GDOS functions 


ppft 


jppii, 


pm 


1 Initialise a graphics device (load driver if necessary) 

2 Stop graphics output to this workstation 

3 Clear display device or move to top of form 

4 Display all pending graphic’s on workstation 

5 Enable device-dependent operation (eg cursor moves, clear line) 

6 Output a polyline 

7 Output markers 

8 Output text, starting at specified position 

9 Display and fill a polygon 

10 Define a cell array 

11 Display a special shape or character (eg bar, arc, pie slice) 

12 Set size for text output 

13 Set text direction 

14 Define the colour associated with a colour index 

15 Set polyline line type 

16 Set polyline linewidth 

17 Set polyline colour index 

18 Set polymarker type 

19 Set polymarker size 

20 Set polymarker colour index 

21 Set device-dependent text style 

22 Set text colour index 

23 Set interior style for polygon fill 

24 Set fill style for polygons 

25 Set colour for polygon fill 

26 Return colour representation values of colour index 

27 Return defenition of cell array 

28 Return value of 'Locator' 

29 Return value of 'Valuator' 

30 Return value of 'choice device' 

31 Return character string input to 'Text Input Device' 

32 Set Writing Mode 

33 Set Input Mode 
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4 GSX drivers provided 


Included within the BBC Microcomputer Z80 Second Processor package are 
device drivers for the BBC Microcomputer screen in mode 0 and 1, plus 
the Epson and OKidata range of printers. 
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DEVICE DRIVERS 



BBC MICROCOMPUTER 

PRINTERS 

DEVICE 

Mode 0 Mode 1 

Epson (Low Res) Epson (High Res) Microline 

DRIVER NAME 

DDBBCO DDBBC1 

DDFXLR8 DDFXHR8 DDOKI84 

LOGICAL 

DEVICE 

0 1 

21 22 23 

RESOLUTION 

640x256 320x256 

480x672 960x1368 824x672 

LINESTYLES 

1 Solid 

2 Dashed (1.5 - 1.5) 

3 Dashed (4.5 - 4.5) 

4 Dashed ( 3 - 1.5 ) 

5 Dashed ( 6 - 1.5 ) 

1 Solid 

2 Short Dash 

3 Dot 

4 Dash-Dot 

5 Long Dash 

6 Dash Dot-Dot 

NUMBER OF 
SIZES 

1 

12 

MARKER 

TYPES 

1 . 

2 + 

3 * 

4 0 

5 X 

TEXT 

- SIZE 

- RESOLUTION 

1 

0 

12 

90 Degree Intervals 

FILL 

AREA 


Hatch or Half-Tone 

1 Oil ID 

2 (H 2 r 

3 W 3 ft 

4 1 4 at 

5 ® 5 p 

6 6 ■ 

GENERALISED 

DRAWING 

PRIMITIVES 

Bar Fill 1 

> Solid 
Pie SlicesJ 

Black/White Red/Green 
Blue/White 

Arcs | 

> Solid 
Circles J 

Black/White Red/Green 
Blue/White 

Bar Fill 

Black/White 

ESCAPES 

No 

Inquire Addressable 

Character Cells 

INPUT 

No 

No 
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